texinfo documentation for sage

[mantepse]

texinfo is the native documentation format to emacs. sphinx can output texinfo. we should use that.

CC: stakemorii@gmail.com @hivert

Component: documentation

Keywords: Sphinx

Author: Martin Rubey

Branch/Commit: u/mantepse/texinfo_documentation_for_sage @ b3dac9d

Issue created by migration from https://trac.sagemath.org/ticket/21734

[mantepse]

Branch: u/mantepse/texinfo_documentation_for_sage

[mantepse]

comment:2

see also https://groups.google.com/forum/#!topic/sage-devel/MjhzbpqnLXs

applying this patch and doing ./sage -docbuild reference texinfo leaves a .texi file and a Makefile in each directory below SAGEROOT/local/share/doc/sage/texinfo/en/reference. Issuing make in each directory then creates a beautiful .info file, which can be visited in emacs using C-u C-h i filename.

Currently I do not know how to make sage make the .info files itself, and I do not know how sage-shell-mode could display them.

---

New commits:

556e8d3

create texi files

[mantepse]

Commit: 556e8d3

[mantepse]

Author: Martin Rubey

[mantepse]

comment:4

I am having some problems with the texinfo-hyperlinks. 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 contre-tableau.

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

[mantepse]

comment:5

Replying to @mantepse:

I am having some problems with the texinfo-hyperlinks. 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.sphinx-doc.org/en/stable/faq.html#texinfo-info but I do not see why they would apply.

[sagetrac-stakemori]

comment:6

Replying to @mantepse:

Thank you for the patch. I attended a conference this week and will try the patch when I go back home.

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

66f2f43

also build info files

[sagetrac-git]

Changed commit from 556e8d3 to 66f2f43

[sagetrac-git]

Changed commit from 66f2f43 to 7012f33

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

7012f33

give the info file the same name as the directory

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

4294647

simplify (images are still not copied)

[sagetrac-git]

Changed commit from 7012f33 to 4294647

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

db003fa

more sensible values in texinfo_documents

[sagetrac-git]

Changed commit from 4294647 to db003fa

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

6774f4f	remove line breaks in rubrics titles
491ad5e	repair removal of newlines

[sagetrac-git]

Changed commit from db003fa to 491ad5e

[mantepse]

comment:12

Florent, if you could help with the problem reported at https://groups.google.com/forum/#!topic/sphinx-users/-8cHf1ZD5S4 that would be great. This seems very much related to #9128!

[mantepse]

Changed keywords from none to Sphinx

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

c73c232

not sure, but I think this needs to set texinfo_documents, too

[sagetrac-git]

Changed commit from 491ad5e to c73c232

[mantepse]

comment:14

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/sphinx-users/-8cHf1ZD5S4 and also on the sphinx github page sphinx-doc/sphinx#3089, but have not got any response so far.

meanwhile, I discovered SAGEROOT/src/doc/common/conf.py, which contains the call app.connect('missing-reference', 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...

[sagetrac-stakemori]

comment:15

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.

[sagetrac-git]

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

[sagetrac-git]

Changed commit from c73c232 to b3dac9d

[jhpalmieri]

comment:17

The reference manual doesn't build for me (html, not texinfo) without this change:

diff --git a/src/doc/en/reference/conf.py b/src/doc/en/reference/conf.py
index 5c7bbe95ec..22961d90ae 100644
--- a/src/doc/en/reference/conf.py
+++ b/src/doc/en/reference/conf.py
@@ -67,7 +67,7 @@ latex_elements['preamble'] += r'''
 # @end direntry
 
 texinfo_documents = [
-('index', name, title, u'The Sage Development Team', name, title, 'SageMath')
+('index', name, project, u'The Sage Development Team', name, project, 'SageMath')
 ]
 
 #Ignore all .rst in the _sage subdirectory

or something similar: title is not defined in reference/conf.py.

[jhpalmieri]

comment:18

You could also consider adding a Makefile target:

diff --git a/build/make/deps b/build/make/deps
index 371a56a767..65ad3fdc07 100644
--- a/build/make/deps
+++ b/build/make/deps
@@ -247,6 +247,8 @@ doc-src-clean:
 doc-output-clean:
        rm -rf "$(SAGE_SHARE)/doc/sage"
 
+doc-texinfo: $(DOC_DEPENDENCIES)
+       $(AM_V_at)cd ../.. && sage-logger -p './sage --docbuild all texinfo $(SAGE_DOCBUILD_OPTS)' logs/doctexinfo.log
 
 ###############################################################################
 # Cleaning up

(After doing this, make doc-texinfo 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 install-info 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?

[mantepse]

comment:19

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 sphinx-doc/sphinx#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!