Opened 5 years ago

Last modified 3 years ago

#21734 new enhancement

texinfo documentation for sage

Reported by: mantepse Owned by:
Priority: major Milestone: sage-7.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:

Status badges

Description (last modified by mantepse)

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 mantepse

  • Branch set to u/mantepse/texinfo_documentation_for_sage

comment:2 Changed 5 years ago by mantepse

  • Authors set to Martin Rubey
  • Cc stakemorii@… added
  • Commit set to 556e8d34f1342929ff817d8eb54dfef58cfbaec5
  • Component changed from PLEASE CHANGE to documentation
  • Description modified (diff)
  • Type changed from PLEASE CHANGE to enhancement

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:

556e8d3create texi files

comment:3 Changed 5 years ago by mantepse

  • Description modified (diff)

comment:4 follow-up: Changed 5 years ago by 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:

@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

comment:5 in reply to: ↑ 4 ; follow-up: Changed 5 years ago by mantepse

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.

comment:6 in reply to: ↑ 5 Changed 5 years ago by stakemori

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 git

  • Commit changed from 556e8d34f1342929ff817d8eb54dfef58cfbaec5 to 66f2f43ed23ccbccf4cf4d3e4ad7a2d2a40648b5

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

66f2f43also build info files

comment:8 Changed 5 years ago by git

  • Commit changed from 66f2f43ed23ccbccf4cf4d3e4ad7a2d2a40648b5 to 7012f33c69874cee2895dcf8699b456ede191427

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

7012f33give the info file the same name as the directory

comment:9 Changed 5 years ago by git

  • Commit changed from 7012f33c69874cee2895dcf8699b456ede191427 to 4294647ac2c4632b156d513af5c17ad2eef74c26

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

4294647simplify (images are still not copied)

comment:10 Changed 5 years ago by git

  • Commit changed from 4294647ac2c4632b156d513af5c17ad2eef74c26 to db003fa7f0506cf1366bbaedfd731ab0c34808b4

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

db003famore sensible values in texinfo_documents

comment:11 Changed 5 years ago by git

  • Commit changed from db003fa7f0506cf1366bbaedfd731ab0c34808b4 to 491ad5ec53e23a75a804f95eefb5b3e9300432c2

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

6774f4fremove line breaks in rubrics titles
491ad5erepair removal of newlines

comment:12 Changed 5 years ago by mantepse

  • Cc hivert added
  • Keywords Sphinx added

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!

comment:13 Changed 5 years ago by git

  • Commit changed from 491ad5ec53e23a75a804f95eefb5b3e9300432c2 to c73c232d9ea0dbcb6bcd19479e62c4cd2375770c

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

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

comment:14 follow-up: Changed 5 years ago by mantepse

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 https://github.com/sphinx-doc/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('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...

comment:15 in reply to: ↑ 14 Changed 5 years ago by stakemori

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 git

  • Commit changed from c73c232d9ea0dbcb6bcd19479e62c4cd2375770c to b3dac9dcc59d01f9d077d71ef0dbcc1e2db93dde

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

b3dac9dMerge branch 'develop' of git://trac.sagemath.org/sage into t/21734/texinfo_documentation_for_sage

comment:17 Changed 3 years ago by jhpalmieri

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''' 
    6767# @end direntry
    6868
    6969texinfo_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')
    7171]
    7272
    7373#Ignore all .rst in the _sage subdirectory

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

comment:18 follow-up: Changed 3 years ago by jhpalmieri

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 doc-src-clean: 
    247247doc-output-clean:
    248248       rm -rf "$(SAGE_SHARE)/doc/sage"
    249249
     250doc-texinfo: $(DOC_DEPENDENCIES)
     251       $(AM_V_at)cd ../.. && sage-logger -p './sage --docbuild all texinfo $(SAGE_DOCBUILD_OPTS)' logs/doctexinfo.log
    250252
    251253###############################################################################
    252254# 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?

comment:19 in reply to: ↑ 18 Changed 3 years ago by mantepse

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

Note: See TracTickets for help on using tickets.