Opened 5 years ago
Last modified 3 years ago
#21734 new enhancement
texinfo documentation for sage
Reported by:  mantepse  Owned by:  

Priority:  major  Milestone:  sage7.5 
Component:  documentation  Keywords:  Sphinx 
Cc:  stakemorii@…, hivert  Merged in:  
Authors:  Martin Rubey  Reviewers:  
Report Upstream:  N/A  Work issues:  
Branch:  u/mantepse/texinfo_documentation_for_sage (Commits, GitHub, GitLab)  Commit:  b3dac9dcc59d01f9d077d71ef0dbcc1e2db93dde 
Dependencies:  Stopgaps: 
Description (last modified by )
texinfo is the native documentation format to emacs. sphinx can output texinfo. we should use that.
Change History (19)
comment:1 Changed 5 years ago by
 Branch set to u/mantepse/texinfo_documentation_for_sage
comment:2 Changed 5 years ago by
 Cc stakemorii@… added
 Commit set to 556e8d34f1342929ff817d8eb54dfef58cfbaec5
 Component changed from PLEASE CHANGE to documentation
 Description modified (diff)
 Type changed from PLEASE CHANGE to enhancement
comment:3 Changed 5 years ago by
 Description modified (diff)
comment:4 followup: ↓ 5 Changed 5 years ago by
I am having some problems with the texinfohyperlinks. For example, in
sage: ASM = AlternatingSignMatrices(3)
the (3)
is interpreted as a link to a footnote. The corresponding bit of the texinfo source looks OK, though:
@geindex from_contre_tableau() (sage.combinat.alternating_sign_matrix.AlternatingSignMatrices method) @anchor{sage/combinat/alternating_sign_matrix sage combinat alternating_sign_matrix AlternatingSignMatrices from_contre_tableau}@anchor{227} @deffn {Method} from_contre_tableau (comps) Return an alternating sign matrix from a contretableau. EXAMPLES: @example sage: ASM = AlternatingSignMatrices(3) sage: ASM.from_contre_tableau([[1, 2, 3], [1, 2], [1]]) [0 0 1] [0 1 0] [1 0 0] sage: ASM.from_contre_tableau([[1, 2, 3], [2, 3], [3]]) [1 0 0] [0 1 0] [0 0 1] @end example @end deffn
comment:5 in reply to: ↑ 4 ; followup: ↓ 6 Changed 5 years ago by
Replying to mantepse:
I am having some problems with the texinfohyperlinks. For example, in
sage: ASM = AlternatingSignMatrices(3)the
(3)
is interpreted as a link to a footnote. The corresponding bit of the texinfo source looks OK, though:
in the standalone info program, this problem does not appear. There are some hints in the Sphinx FAQ http://www.sphinxdoc.org/en/stable/faq.html#texinfoinfo but I do not see why they would apply.
comment:6 in reply to: ↑ 5 Changed 5 years ago by
Replying to mantepse:
Thank you for the patch. I attended a conference this week and will try the patch when I go back home.
comment:7 Changed 5 years ago by
 Commit changed from 556e8d34f1342929ff817d8eb54dfef58cfbaec5 to 66f2f43ed23ccbccf4cf4d3e4ad7a2d2a40648b5
Branch pushed to git repo; I updated commit sha1. New commits:
66f2f43  also build info files

comment:8 Changed 5 years ago by
 Commit changed from 66f2f43ed23ccbccf4cf4d3e4ad7a2d2a40648b5 to 7012f33c69874cee2895dcf8699b456ede191427
Branch pushed to git repo; I updated commit sha1. New commits:
7012f33  give the info file the same name as the directory

comment:9 Changed 5 years ago by
 Commit changed from 7012f33c69874cee2895dcf8699b456ede191427 to 4294647ac2c4632b156d513af5c17ad2eef74c26
Branch pushed to git repo; I updated commit sha1. New commits:
4294647  simplify (images are still not copied)

comment:10 Changed 5 years ago by
 Commit changed from 4294647ac2c4632b156d513af5c17ad2eef74c26 to db003fa7f0506cf1366bbaedfd731ab0c34808b4
Branch pushed to git repo; I updated commit sha1. New commits:
db003fa  more sensible values in texinfo_documents

comment:11 Changed 5 years ago by
 Commit changed from db003fa7f0506cf1366bbaedfd731ab0c34808b4 to 491ad5ec53e23a75a804f95eefb5b3e9300432c2
comment:12 Changed 5 years ago by
 Cc hivert added
 Keywords Sphinx added
Florent, if you could help with the problem reported at https://groups.google.com/forum/#!topic/sphinxusers/8cHf1ZD5S4 that would be great. This seems very much related to #9128!
comment:13 Changed 5 years ago by
 Commit changed from 491ad5ec53e23a75a804f95eefb5b3e9300432c2 to c73c232d9ea0dbcb6bcd19479e62c4cd2375770c
Branch pushed to git repo; I updated commit sha1. New commits:
c73c232  not sure, but I think this needs to set texinfo_documents, too

comment:14 followup: ↓ 15 Changed 5 years ago by
Dear Sho,
unfortunately, I still have no clue how to enable the crossreferences between the individual manuals. I asked on the sphinx user group https://groups.google.com/forum/#!topic/sphinxusers/8cHf1ZD5S4 and also on the sphinx github page https://github.com/sphinxdoc/sphinx/issues/3089, but have not got any response so far.
meanwhile, I discovered SAGEROOT/src/doc/common/conf.py
, which contains the call app.connect('missingreference', find_sage_dangling_links)
.
I suspect that this (I mean find_sage_dangling_links
) is where I should put the proper handling for texinfo crossreferences, but I'm not sure yet...
comment:15 in reply to: ↑ 14 Changed 5 years ago by
Replying to mantepse:
It is already convenient to view Sage document via info. Thank you very much. Concerning with sphinx, I cannot help you, sorry.
comment:16 Changed 3 years ago by
 Commit changed from c73c232d9ea0dbcb6bcd19479e62c4cd2375770c to b3dac9dcc59d01f9d077d71ef0dbcc1e2db93dde
Branch pushed to git repo; I updated commit sha1. New commits:
b3dac9d  Merge branch 'develop' of git://trac.sagemath.org/sage into t/21734/texinfo_documentation_for_sage

comment:17 Changed 3 years ago by
The reference manual doesn't build for me (html, not texinfo) without this change:

src/doc/en/reference/conf.py
diff git a/src/doc/en/reference/conf.py b/src/doc/en/reference/conf.py index 5c7bbe95ec..22961d90ae 100644
a b latex_elements['preamble'] += r''' 67 67 # @end direntry 68 68 69 69 texinfo_documents = [ 70 ('index', name, title, u'The Sage Development Team', name, title, 'SageMath')70 ('index', name, project, u'The Sage Development Team', name, project, 'SageMath') 71 71 ] 72 72 73 73 #Ignore all .rst in the _sage subdirectory
or something similar: title
is not defined in reference/conf.py
.
comment:18 followup: ↓ 19 Changed 3 years ago by
You could also consider adding a Makefile
target:

build/make/deps
diff git a/build/make/deps b/build/make/deps index 371a56a767..65ad3fdc07 100644
a b docsrcclean: 247 247 docoutputclean: 248 248 rm rf "$(SAGE_SHARE)/doc/sage" 249 249 250 doctexinfo: $(DOC_DEPENDENCIES) 251 $(AM_V_at)cd ../.. && sagelogger p './sage docbuild all texinfo $(SAGE_DOCBUILD_OPTS)' logs/doctexinfo.log 250 252 251 253 ############################################################################### 252 254 # Cleaning up
(After doing this, make doctexinfo
fails for me when building the developer's guide, by the way.) Then someone who is better at make
than I am could possibly add a target to run make
in all of the subdirectories of local/share/doc/sage/texinfo
. It could be a bit of a mess, but we could instead set $infodir
to point to local/share/info
and then run make installinfo
instead of make
. The problem is that texinfo/de/tutorial/sagetutorial.texi
and texinfo/en/tutorial/sagetutorial.texi
will produce .info
files of the same name. Does info
handle subdirectories well? Should we have local/share/info/de/
or local/share/info/sage/de/
, etc.? The Sage reference manual will also consist of lots of separate .info
files; how should those be handled?
comment:19 in reply to: ↑ 18 Changed 3 years ago by
Thank you for looking into this!
I'm afraid, however, that there is a shostopper: I couldn't get the links between the individual texinfo files to work. I filed https://github.com/sphinxdoc/sphinx/issues/3089 but it was closed. The advice was: "Please integrate your project into single one."
It may well be that I misunderstood the whole thing  but as far as I could tell at the time, the sage documentation consists of many subprojects, one for each folder below src/sage
. If that's not the case, that would be great and I'd be happy to learn more about it!
see also https://groups.google.com/forum/#!topic/sagedevel/MjhzbpqnLXs
applying this patch and doing
./sage docbuild reference texinfo
leaves a.texi
file and aMakefile
in each directory belowSAGEROOT/local/share/doc/sage/texinfo/en/reference
. Issuingmake
in each directory then creates a beautiful.info
file, which can be visited in emacs usingCu Ch i filename
.Currently I do not know how to make sage
make
the.info
files itself, and I do not know howsageshellmode
could display them.New commits:
create texi files