Opened 5 years ago

Closed 5 years ago

Last modified 5 years ago

#16058 closed enhancement (fixed)

Organize the index of the combinatorics section of the reference manual

Reported by: ncohen Owned by:
Priority: major Milestone: sage-6.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 ncohen

  • Branch set to public/16058
  • Commit set to 8b8aea8ff2f3e1002d822b0ea1fd8ebb263597de
  • Status changed from new to needs_review

New commits:

8b8aea8trac #16058: Organize the index of combinatorial modules

comment:2 Changed 5 years ago by git

  • Commit changed from 8b8aea8ff2f3e1002d822b0ea1fd8ebb263597de to e0d2b660de55ffd6236cafd80737e3aa46d48fd3

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

e0d2b66trac #16058: Two new categories

comment:3 Changed 5 years ago by git

  • Commit changed from e0d2b660de55ffd6236cafd80737e3aa46d48fd3 to 0293c49d6f4ab8003d25844479ea76a4a94e76cf

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

0293c49trac #16058: Another group

comment:4 Changed 5 years ago by nthiery

  • Summary changed from Organize the index of combinatorial modules to Organize the index of the combinatorics section of the reference manual

comment:5 follow-up: Changed 5 years ago by nthiery

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

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

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

comment:7 Changed 5 years ago by git

  • Commit changed from 0293c49d6f4ab8003d25844479ea76a4a94e76cf to a14057b592426b65a80ba3e4aca4dd0818e2cec8

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

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

comment:8 Changed 5 years ago by tscrim

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 git

  • Commit changed from a14057b592426b65a80ba3e4aca4dd0818e2cec8 to 50cb82789bb0d70ac3f0e52104a1b533f050de9b

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

50cb827trac #16058: Rebase on 6.2.rc0

comment:10 Changed 5 years ago by git

  • Commit changed from 50cb82789bb0d70ac3f0e52104a1b533f050de9b to 4b5cb2beed23b92bf27529fca72e89db8754f6d5

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

4b5cb2btrac #16058: Rebase on 6.2.rc0

comment:11 Changed 5 years ago by ncohen

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 follow-up: Changed 5 years ago by nthiery

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

comment:13 in reply to: ↑ 12 ; follow-up: Changed 5 years ago by ncohen

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

comment:14 in reply to: ↑ 13 Changed 5 years ago by nthiery

Replying to ncohen:

Discussion moved to #16256.

comment:15 follow-up: Changed 5 years ago by ncohen

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

Version 0, edited 5 years ago by ncohen (next)

comment:16 in reply to: ↑ 15 Changed 5 years ago by nthiery

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 ncohen

Still waiting for review ...

comment:18 Changed 5 years ago by nthiery

  • Status changed from needs_review to positive_review

comment:19 Changed 5 years ago by nthiery

Good to go!

comment:20 Changed 5 years ago by nthiery

  • Authors set to Nathann Cohen, Travis Scrimshaw
  • Reviewers set to Nicolas M. Thiéry

And thanks Nathann and Travis for improving our user experience!

comment:21 Changed 5 years ago by vbraun

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

  • Commit 4b5cb2beed23b92bf27529fca72e89db8754f6d5 deleted

Thaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaanks !!!

Note: See TracTickets for help on using tickets.