Organize the index of the combinatorics section of the reference manual
Closed this issue · 30 comments
This page is a bit messy :
http://www.sagemath.org/doc/reference/combinat/index.html
The goal of this ticket is to make it easier to read, in the hope to find what one is actually looking for.
Everybody is welcome to add a commit to group/sort everything here in a way that will satisfy the specialist of each field.
Nathann
Component: combinatorics
Author: Nathann Cohen, Travis Scrimshaw
Branch: 4b5cb2b
Reviewer: Nicolas M. Thiéry
Issue created by migration from https://trac.sagemath.org/ticket/16058
New commits:
8b8aea8 | trac #16058: Organize the index of combinatorial modules |
Commit: 8b8aea8
Branch: public/16058
Branch pushed to git repo; I updated commit sha1. New commits:
e0d2b66 | trac #16058: Two new categories |
Branch pushed to git repo; I updated commit sha1. New commits:
0293c49 | trac #16058: Another group |
Hi!
I have been toying around with Florent and others, but it makes me want to do some deeper changes and so is nowhere near to converge. Experimental and completely messed up branch: u/nthiery/16058-combinat-doc-index. This will be easier to handle now that #16100 fixed the error reporting in the documentation compilation!
Cheers,
Nicolas
I have been toying around with Florent and others, but it makes me want to do some deeper changes and so is nowhere near to converge.
If your method does not converge, then try another method. This index is impossible to read, almost any improvement makes a huge difference.
Experimental and completely messed up branch: u/nthiery/16058-combinat-doc-index. This will be easier to handle now that #16100 fixed the error reporting in the documentation compilation!
I will not be available for a week or so (no computer to run Sage and everything). Try to do the best you can during that time. Have fun !
Nathann
Branch pushed to git repo; I updated commit sha1. New commits:
a14057b | Some more groupings and separated root system types into separate list. |
With this format, we probably can also do away with some of the subindex rst files too. Anyways, I've just pushed some more groupings and separated the type_* part of the root systems into a separate file so it one doesn't have to see that at the higher levels of the doc.
Branch pushed to git repo; I updated commit sha1. New commits:
50cb827 | trac #16058: Rebase on 6.2.rc0 |
Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:
4b5cb2b | trac #16058: Rebase on 6.2.rc0 |
Rebased on the latest release, with a new section for finite state machines.
Now guys, to me this looks fine and at the very least much better than what we had before. Could any of you give this ticket a positive review if you agree with it ?
There will be a new release soon, and it would be cool if this patch is in before the official documentation is updated to match the next release.
Nathann
What the heck??? Why didn't my advertising for all the hard work I had put on my branch last week-end end up here? I must say I was surprised not to get feedback ...
Oh well. Here is my commit log:
Trac 16058: Reorganize the documentation indexes into src/sage/combinat
- For example, the thematic index
src/doc/en/reference/combinat/crystals.rst is now in:
src/sage/combinat/crystals/__init__.py and is accessible through
sage.combinat.crystals?
(to be discussed: should this be put in all.py instead?)
- What's left in doc/en/reference/combinat is basically autogenerated.
(the building of module_list.rst there still needs to be regenerated by hand)
- All p/cython files in sage/combinat/ are now included in the reference manual
- Improved thematic indexes
- New thematic indexes: algebraic_combinatorics, catalog_partitions,
counting, enumerated_sets
- Fixed some documentation syntax glitches here and there
- Added the catalogs of permutation groups and matrix groups to the
reference manual so that we can link to them.
- Draft of sage.combinat.quickref
TODO:
- proof reading
- choosing the right entry points
- checking that the links are functional
- deciding on how to link to classes/functions (in the index we would
want to have the title of the documentation of the class rather than
the name of the class. Or maybe both).
Please have a look at u/nthiery/16058-combinat-doc-index, and at the
current end-result:
http://sage.math.washington.edu/home/nthiery/16058-doc/combinat/index.html
One might argue that this reorganization of the documentation is not
consistent with what's done elsewhere in the manual. Indeed. I believe
sage.combinat is a good spot to explore better ways to organize the
documentation. I also believe that this new way is more local,
simpler, and more flexible. It might benefit from a bit more support
from sphinx though
If you think the change is a bit radical and you prefer merging the
current official branch as it is now, and postponing mine to a later
ticket, that's fine with me.
Cheers,
Nicolas
What the heck??? Why didn't my advertising for all the hard work I had put on my branch last week-end end up here? I must say I was surprised not to get feedback ...
....
Oh well. Here is my commit log:
-
I have no idea how I can obtain the result from your web page with the branch you give. By the way, it does not apply on the latest rc0.
-
Look at that : http://sage.math.washington.edu/home/nthiery/16058-doc/combinat/sage/combinat/counting.html#sage-combinat-counting
Or that : http://sage.math.washington.edu/home/nthiery/16058-doc/combinat/sage/combinat/species/__init__.html#sage-combinat-species
All links are broken ! That's a problem for a reference manual ...
-
Where are the combinatorial designs ?
-
Those TODO will have to be removed before it is merged anywhere.
Nicolas, it looks like your branch is not ready. Could you review this ticket and create another one for yours ? You would also need to ask the release manager what he thinks of the script you have to run before generating the doc. Perhaps there is a pure-sphinx workaround ? I guess you asked Florent about this too ?
Right now I have no idea how it works. If you create another ticket, please explain that.
Nathann
Okayyyyyyyyyyyy !
Could you explain how it works, how to reproduce the doc page that you have on your website, and why designs do not appear ?
Could you also give this ticket a review if you agree with it ? I will then send an email to Volker to ask him if he can include it in the next release.
Nathann
Replying to @nathanncohen:
Could you explain how it works, how to reproduce the doc page that you have on your website, and why designs do not appear ?
Could you also give this ticket a review if you agree with it ? I will then send an email to Volker to ask him if he can include it in the next release.
Yes, yes, just leave me the time to type :-)
Still waiting for review ...
Good to go!
Author: Nathann Cohen, Travis Scrimshaw
And thanks Nathann and Travis for improving our user experience!
Reviewer: Nicolas M. Thiéry
Changed branch from public/16058 to 4b5cb2b
Thaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaanks !!!
Changed commit from 4b5cb2b to none