#16058 closed enhancement (fixed)
Organize the index of the combinatorics section of the reference manual
Reported by:  ncohen  Owned by:  

Priority:  major  Milestone:  sage6.2 
Component:  combinatorics  Keywords:  
Cc:  Merged in:  
Authors:  Nathann Cohen, Travis Scrimshaw  Reviewers:  Nicolas M. Thiéry 
Report Upstream:  N/A  Work issues:  
Branch:  4b5cb2b (Commits)  Commit:  
Dependencies:  Stopgaps: 
Description
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
Change History (22)
comment:1 Changed 5 years ago by
 Branch set to public/16058
 Commit set to 8b8aea8ff2f3e1002d822b0ea1fd8ebb263597de
 Status changed from new to needs_review
comment:2 Changed 5 years ago by
 Commit changed from 8b8aea8ff2f3e1002d822b0ea1fd8ebb263597de to e0d2b660de55ffd6236cafd80737e3aa46d48fd3
Branch pushed to git repo; I updated commit sha1. New commits:
e0d2b66  trac #16058: Two new categories

comment:3 Changed 5 years ago by
 Commit changed from e0d2b660de55ffd6236cafd80737e3aa46d48fd3 to 0293c49d6f4ab8003d25844479ea76a4a94e76cf
Branch pushed to git repo; I updated commit sha1. New commits:
0293c49  trac #16058: Another group

comment:4 Changed 5 years ago by
 Summary changed from Organize the index of combinatorial modules to Organize the index of the combinatorics section of the reference manual
comment:5 followup: ↓ 6 Changed 5 years ago by
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/16058combinatdocindex. This will be easier to handle now that #16100 fixed the error reporting in the documentation compilation!
Cheers,
Nicolas
comment:6 in reply to: ↑ 5 Changed 5 years ago by
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/16058combinatdocindex. 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
comment:7 Changed 5 years ago by
 Commit changed from 0293c49d6f4ab8003d25844479ea76a4a94e76cf to a14057b592426b65a80ba3e4aca4dd0818e2cec8
Branch pushed to git repo; I updated commit sha1. New commits:
a14057b  Some more groupings and separated root system types into separate list.

comment:8 Changed 5 years ago by
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.
comment:9 Changed 5 years ago by
 Commit changed from a14057b592426b65a80ba3e4aca4dd0818e2cec8 to 50cb82789bb0d70ac3f0e52104a1b533f050de9b
Branch pushed to git repo; I updated commit sha1. New commits:
50cb827  trac #16058: Rebase on 6.2.rc0

comment:10 Changed 5 years ago by
 Commit changed from 50cb82789bb0d70ac3f0e52104a1b533f050de9b to 4b5cb2beed23b92bf27529fca72e89db8754f6d5
Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:
4b5cb2b  trac #16058: Rebase on 6.2.rc0

comment:11 Changed 5 years ago by
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
comment:12 followup: ↓ 13 Changed 5 years ago by
What the heck??? Why didn't my advertising for all the hard work I had put on my branch last weekend 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/16058combinatdocindex, and at the current endresult:
http://sage.math.washington.edu/home/nthiery/16058doc/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
comment:13 in reply to: ↑ 12 ; followup: ↓ 14 Changed 5 years ago by
What the heck??? Why didn't my advertising for all the hard work I had put on my branch last weekend end up here? I must say I was surprised not to get feedback ...
....
Oh well. Here is my commit log:
1) 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.
2) Look at that : http://sage.math.washington.edu/home/nthiery/16058doc/combinat/sage/combinat/counting.html#sagecombinatcounting Or that : http://sage.math.washington.edu/home/nthiery/16058doc/combinat/sage/combinat/species/__init__.html#sagecombinatspecies
All links are broken ! That's a problem for a reference manual ...
3) Where are the combinatorial designs ?
4) 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 puresphinx 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
comment:14 in reply to: ↑ 13 Changed 5 years ago by
comment:15 followup: ↓ 16 Changed 5 years ago by
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 ?
Couldd 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
comment:16 in reply to: ↑ 15 Changed 5 years ago by
Replying to ncohen:
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 :)
comment:17 Changed 5 years ago by
Still waiting for review ...
comment:18 Changed 5 years ago by
 Status changed from needs_review to positive_review
comment:19 Changed 5 years ago by
Good to go!
comment:20 Changed 5 years ago by
 Reviewers set to Nicolas M. Thiéry
And thanks Nathann and Travis for improving our user experience!
comment:21 Changed 5 years ago by
 Branch changed from public/16058 to 4b5cb2beed23b92bf27529fca72e89db8754f6d5
 Resolution set to fixed
 Status changed from positive_review to closed
comment:22 Changed 5 years ago by
 Commit 4b5cb2beed23b92bf27529fca72e89db8754f6d5 deleted
Thaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaanks !!!
New commits:
trac #16058: Organize the index of combinatorial modules