Opened 6 years ago
Closed 6 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, GitHub, GitLab) | Commit: | 781d307faa49404848e7bb685937c38eff3508db |
Dependencies: | Stopgaps: |
Description (last modified by )
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 6 years ago by
- Branch set to public/17634
- Status changed from new to needs_review
comment:2 Changed 6 years ago by
- Commit set to adffa81b264ca4414d96e6f2d4bcc51b7e003c34
comment:3 Changed 6 years ago by
- Description modified (diff)
comment:4 follow-up: ↓ 6 Changed 6 years ago by
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 6 years ago by
- Commit changed from adffa81b264ca4414d96e6f2d4bcc51b7e003c34 to 95e886497f4b07fb5f3a795cca4ca5998377c47d
Branch pushed to git repo; I updated commit sha1. New commits:
95e8864 | trac #17634: Review
|
comment:6 in reply to: ↑ 4 Changed 6 years ago by
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 6 years ago by
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 6 years ago by
I'm sorry Karl, I don't know how to make it better.
Nathann
comment:9 Changed 6 years ago by
- Description modified (diff)
comment:10 Changed 6 years ago by
- Status changed from needs_review to needs_work
Do not replace
sage --docbuild
by
sage -docbuild
comment:11 Changed 6 years ago by
Why? I always use it, and it works?..
Nathann
comment:12 Changed 6 years ago by
- Commit changed from 95e886497f4b07fb5f3a795cca4ca5998377c47d to f0bfd0ea0fbe0877b2bba5f6151d6d1aaedcf58f
Branch pushed to git repo; I updated commit sha1. New commits:
f0bfd0e | trac #17634: review
|
comment:13 Changed 6 years ago by
- Status changed from needs_work to needs_review
comment:14 follow-up: ↓ 16 Changed 6 years ago by
- 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 6 years ago by
- Commit changed from f0bfd0ea0fbe0877b2bba5f6151d6d1aaedcf58f to cd6a363a5fb801d33dd24ffcf2835ba4c84129f7
comment:16 in reply to: ↑ 14 Changed 6 years ago by
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 6 years ago by
- Status changed from needs_work to needs_review
comment:18 follow-up: ↓ 19 Changed 6 years ago by
- 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 6 years ago by
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: ↓ 21 Changed 6 years ago by
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 6 years ago by
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 6 years ago by
As you know, for me it is somewhat longer to create all those things :-)
comment:23 Changed 6 years ago by
[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 6 years ago by
- Status changed from positive_review to needs_work
comment:25 Changed 6 years ago by
- Commit changed from cd6a363a5fb801d33dd24ffcf2835ba4c84129f7 to 781d307faa49404848e7bb685937c38eff3508db
Branch pushed to git repo; I updated commit sha1. New commits:
781d307 | trac #17634: Broken doc
|
comment:26 Changed 6 years ago by
- 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 6 years ago by
- 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 6 years ago by
Thanks
comment:29 Changed 6 years ago by
- Branch changed from public/17634 to 781d307faa49404848e7bb685937c38eff3508db
- Resolution set to fixed
- Status changed from positive_review to closed
Branch pushed to git repo; I updated commit sha1. New commits:
trac #17634: Rephrase the 'sage manuals' section of the developer manual
trac #17634: Move the sws2rst tutorial to the thematic tutorials