Rephrase the 'sage manuals' section of the developer manual

[nathanncohen]

As for the previous tickets, this branch is meant to make it easier to browse through. Shorter sentences, links, bold text.

This branch also moves (without changing anything) the tutorial on 'How to turn a sws file into a rst file' as it is not about Sage's internal documentation nor about Sage development.

I also fixed the documentation about 'how to add a file to the doc', as the example used the combinat/ folder which since #16256 has a different procedure for that.

CC: @kcrisman @jhpalmieri @videlec @sagetrac-tmonteil

Component: documentation

Author: Nathann Cohen

Branch/Commit: 781d307

Reviewer: Jeroen Demeyer, Karl-Dieter Crisman, Marc Mezzarobba

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

[nathanncohen]

Branch: public/17634

[sagetrac-git]

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

df6a516	trac #17634: Rephrase the 'sage manuals' section of the developer manual
adffa81	trac #17634: Move the sws2rst tutorial to the thematic tutorials

[sagetrac-git]

Commit: adffa81

[kcrisman]

comment:4

I've been away from computer all day and don't have time to look at this in detail, but if you really think that moving the sws2rst thing out is a good idea, there had better be a link to wherever you move it to in the developer guide. The reason that document even exists is because someone wanted to contribute to the thematic tutorials (hence, to be a developer!) and couldn't figure out how to do it without writing her own document to explain it. So it was clearly valuable in the developer sense, turning things not just into rst files but into contributed documentation. Does that explain it sufficiently? Sorry if it's confusing because of my hurry.

[sagetrac-git]

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

95e8864

trac #17634: Review

[sagetrac-git]

Changed commit from adffa81 to 95e8864

[nathanncohen]

comment:6

Hello Karl-Dieter,

Does that work for you? I tried to add it at a place where those who are interested are sure to see it, while making it not too intrusive. It ends up being the first thing that everybody will read ;-)

Nathann

[kcrisman]

comment:7

I'm really sorry I don't have time to think about this properly. Maybe it's a little too early there :-) but my bigger worry is whether that link will be brittle.

[nathanncohen]

comment:8

I'm sorry Karl, I don't know how to make it better.

Nathann

[jdemeyer]

comment:10

Do not replace

sage --docbuild

by

sage -docbuild

[nathanncohen]

comment:11

Why? I always use it, and it works?..

Nathann

[sagetrac-git]

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

f0bfd0e

trac #17634: review

[sagetrac-git]

Changed commit from 95e8864 to f0bfd0e

[kcrisman]

Reviewer: Jeroen Demeyer, Karl-Dieter Crisman

[kcrisman]

comment:14

For some reason this branch is red.

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

e99330c	trac #17634: Rephrase the 'sage manuals' section of the developer manual
6cde12b	trac #17634: Move the sws2rst tutorial to the thematic tutorials
537107a	trac #17634: Review
cd6a363	trac #17634: review

[sagetrac-git]

Changed commit from f0bfd0e to cd6a363

[nathanncohen]

comment:16

For some reason this branch is red.

There were conflicts with several other doc branches that got merged in the meantime. I just rebased it.

Nathann

[kcrisman]

comment:18

I note that we now have

Thematic Tutorials v6.5.rc0 » Thematic tutorial document tree »

which seems a little odd. Shouldn't it just be one level? Anyway, no doubt this stems from one of the other tickets you mentioned.

[nathanncohen]

comment:19

I note that we now have

Thematic Tutorials v6.5.rc0 » Thematic tutorial document tree »

which seems a little odd. Shouldn't it just be one level? Anyway, no doubt this stems from one of the other tickets you mentioned.

I think that it is because of the toctree.rst files. If I understand correctly, Sphinx will not detect a rst file as "indexed" unless it appears in some toctree. The current methodology seems to be the following

1. Create a toctree.rst file that only contains a toctree
2. Point to toctree.rst in the index file where nobody notices it

This way the toctree appears as far as Sphinx is concerned, and we are free to order the modules as we like instead of letting Sphinx do the job with a big 'toctree'.

This being said, I would say that simplifying this could be possible by just having this toctreee in the index.rst file and adding the 'hidden' SphinX keyword.

Plus we would not have to carry a reference to the toctree.rst file when we do not want one.

Thanks for your review,

Nathann

[kcrisman]

comment:20

This way the toctree appears as far as Sphinx is concerned, and we are free to order the modules as we like instead of letting Sphinx do the job with a big 'toctree'. This being said, I would say that simplifying this could be possible by just having this toctreee in the index.rst file and adding the 'hidden' SphinX keyword.

I would be happy to look at any ticket you happen to create that solves this. It would be really unfortunate to have these extra layers of links floating around for any length of time, but I also understand it's not going to be anyone's highest priority (over, say, doing math).

[nathanncohen]

comment:21

I would be happy to look at any ticket you happen to create that solves this.

It really is not very long to give the 'hidden' trick a try when you notice one. 5 minutes is all it takes to create the branch and the ticket.

Nathann

[kcrisman]

comment:22

As you know, for me it is somewhat longer to create all those things :-)

[mezzarobba]

comment:23

[thematic_] /home/marc/co/sage/src/doc/en/thematic_tutorials/sws2rst.rst:43: WARNING: undefined label: section-add-file (if the link has no caption the label must precede a section header)
Error building the documentation.
Traceback (most recent call last):
  File "/home/marc/co/sage/src/doc/common/builder.py", line 1623, in <module>
    getattr(get_builder(name), type)()
  File "/home/marc/co/sage/src/doc/common/builder.py", line 306, in _wrapper
    x.get(99999)
  File "/home/marc/co/sage/local/lib/python/multiprocessing/pool.py", line 558, in get
    raise self._value
OSError: [thematic_] /home/marc/co/sage/src/doc/en/thematic_tutorials/sws2rst.rst:43: WARNING: undefined label: section-add-file (if the link has no caption the label must precede a section header)

[sagetrac-git]

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

781d307

trac #17634: Broken doc

[sagetrac-git]

Changed commit from cd6a363 to 781d307

[nathanncohen]

comment:26

Sorry about that. I had not noticed :-/

This commit fixes it, by redirecting toward the developer's manual.

Nathann

[mezzarobba]

Changed reviewer from Jeroen Demeyer, Karl-Dieter Crisman to Jeroen Demeyer, Karl-Dieter Crisman, Marc Mezzarobba

[nathanncohen]

comment:28

Thanks

[vbraun]

Changed branch from public/17634 to 781d307