Organize the index of the combinatorics section of the reference manual

[nathanncohen]

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

[nathanncohen]

New commits:

8b8aea8

trac #16058: Organize the index of combinatorial modules

[nathanncohen]

Commit: 8b8aea8

[nathanncohen]

Branch: public/16058

[sagetrac-git]

Changed commit from 8b8aea8 to e0d2b66

[sagetrac-git]

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

e0d2b66

trac #16058: Two new categories

[sagetrac-git]

Changed commit from e0d2b66 to 0293c49

[sagetrac-git]

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

0293c49

trac #16058: Another group

[nthiery]

comment:5

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

[nathanncohen]

comment:6

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

[sagetrac-git]

Changed commit from 0293c49 to a14057b

[sagetrac-git]

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

a14057b

Some more groupings and separated root system types into separate list.

[tscrim]

comment:8

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.

[sagetrac-git]

Changed commit from a14057b to 50cb827

[sagetrac-git]

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

50cb827

trac #16058: Rebase on 6.2.rc0

[sagetrac-git]

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

4b5cb2b

trac #16058: Rebase on 6.2.rc0

[sagetrac-git]

Changed commit from 50cb827 to 4b5cb2b

[nathanncohen]

comment:11

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

[nthiery]

comment:12

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

[nathanncohen]

comment:13

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:

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

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

[nthiery]

comment:14

Replying to @nathanncohen:

Discussion moved to #16256.

[nathanncohen]

comment:15

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

[nthiery]

comment:16

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

[nathanncohen]

comment:17

Still waiting for review ...

[nthiery]

comment:19

Good to go!

[nthiery]

Author: Nathann Cohen, Travis Scrimshaw

[nthiery]

comment:20

And thanks Nathann and Travis for improving our user experience!

[nthiery]

Reviewer: Nicolas M. Thiéry

[vbraun]

Changed branch from public/16058 to 4b5cb2b

[nathanncohen]

comment:22

Thaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaanks !!!

[nathanncohen]

Changed commit from 4b5cb2b to none