Opened 4 years ago

Closed 4 years ago

#17634 closed enhancement (fixed)

Rephrase the 'sage manuals' section of the developer manual

Reported by: ncohen Owned by:
Priority: major Milestone: sage-6.5
Component: documentation Keywords:
Cc: kcrisman, jhpalmieri, vdelecroix, tmonteil Merged in:
Authors: Nathann Cohen Reviewers: Jeroen Demeyer, Karl-Dieter Crisman, Marc Mezzarobba
Report Upstream: N/A Work issues:
Branch: 781d307 (Commits) Commit: 781d307faa49404848e7bb685937c38eff3508db
Dependencies: Stopgaps:

Description (last modified by ncohen)

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.

Change History (29)

comment:1 Changed 4 years ago by ncohen

  • Branch set to public/17634
  • Status changed from new to needs_review

comment:2 Changed 4 years ago by git

  • Commit set to adffa81b264ca4414d96e6f2d4bcc51b7e003c34

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

df6a516trac #17634: Rephrase the 'sage manuals' section of the developer manual
adffa81trac #17634: Move the sws2rst tutorial to the thematic tutorials

comment:3 Changed 4 years ago by ncohen

  • Description modified (diff)

comment:4 follow-up: Changed 4 years ago by kcrisman

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.

comment:5 Changed 4 years ago by git

  • Commit changed from adffa81b264ca4414d96e6f2d4bcc51b7e003c34 to 95e886497f4b07fb5f3a795cca4ca5998377c47d

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

95e8864trac #17634: Review

comment:6 in reply to: ↑ 4 Changed 4 years ago by ncohen

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

comment:7 Changed 4 years ago by kcrisman

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.

comment:8 Changed 4 years ago by ncohen

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

Nathann

comment:9 Changed 4 years ago by ncohen

  • Description modified (diff)

comment:10 Changed 4 years ago by jdemeyer

  • Status changed from needs_review to needs_work

Do not replace

sage --docbuild

by

sage -docbuild

comment:11 Changed 4 years ago by ncohen

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

Nathann

comment:12 Changed 4 years ago by git

  • Commit changed from 95e886497f4b07fb5f3a795cca4ca5998377c47d to f0bfd0ea0fbe0877b2bba5f6151d6d1aaedcf58f

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

f0bfd0etrac #17634: review

comment:13 Changed 4 years ago by ncohen

  • Status changed from needs_work to needs_review

comment:14 follow-up: Changed 4 years ago by kcrisman

  • Reviewers set to Jeroen Demeyer, Karl-Dieter Crisman
  • Status changed from needs_review to needs_work

For some reason this branch is red.

comment:15 Changed 4 years ago by git

  • Commit changed from f0bfd0ea0fbe0877b2bba5f6151d6d1aaedcf58f to cd6a363a5fb801d33dd24ffcf2835ba4c84129f7

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

e99330ctrac #17634: Rephrase the 'sage manuals' section of the developer manual
6cde12btrac #17634: Move the sws2rst tutorial to the thematic tutorials
537107atrac #17634: Review
cd6a363trac #17634: review

comment:16 in reply to: ↑ 14 Changed 4 years ago by ncohen

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

comment:17 Changed 4 years ago by ncohen

  • Status changed from needs_work to needs_review

comment:18 follow-up: Changed 4 years ago by kcrisman

  • Status changed from needs_review to positive_review

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.

comment:19 in reply to: ↑ 18 Changed 4 years ago by ncohen

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

comment:20 follow-up: Changed 4 years ago by kcrisman

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).

comment:21 in reply to: ↑ 20 Changed 4 years ago by ncohen

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

comment:22 Changed 4 years ago by kcrisman

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

comment:23 Changed 4 years ago by mmezzarobba

[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)

comment:24 Changed 4 years ago by mmezzarobba

  • Status changed from positive_review to needs_work

comment:25 Changed 4 years ago by git

  • Commit changed from cd6a363a5fb801d33dd24ffcf2835ba4c84129f7 to 781d307faa49404848e7bb685937c38eff3508db

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

781d307trac #17634: Broken doc

comment:26 Changed 4 years ago by ncohen

  • Status changed from needs_work to needs_review

Sorry about that. I had not noticed :-/

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

Nathann

comment:27 Changed 4 years ago by mmezzarobba

  • Reviewers changed from Jeroen Demeyer, Karl-Dieter Crisman to Jeroen Demeyer, Karl-Dieter Crisman, Marc Mezzarobba
  • Status changed from needs_review to positive_review

comment:28 Changed 4 years ago by ncohen

Thanks

comment:29 Changed 4 years ago by vbraun

  • Branch changed from public/17634 to 781d307faa49404848e7bb685937c38eff3508db
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.