Goal: 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?

  (potential variant: put it in all.py)

• What's left in doc/en/reference/combinat can potentially be generated automatically.
  This is not yet automatized; the content of module_list.rst still needs to be updated by hand; see the instructions on top of the file.

• All p/cython files in src/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. Fixed the doc title of
  the former.

• Added a back link from the doc of sage.dynamics

• Added (draft of) sage.combinat.quickref

This is a follow up to #16058.

End result browsable at ​http://sage.math.washington.edu/home/nthiery/sage/src/doc/output/html/en/reference/combinat/index.html

Warning: see the note below about the current doc compilation glitch.

Discussion

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. Here are the advantages of this new organization:

• It's more local:

  E.g. everything the developer has to look at or modify about
  designs, including the index, is in src/sage/combinat/design. This
  is simpler for newcomers and means, e. g., less chances to forget to
  update the index w.r.t. the code.

• It's more consistent with the hierarchical structure of modules. In
  particular, it's agnostic of how the reference manual is split into
  documents. This was not the case before: to split
  sage/combinat/crystals in its own document required to move the
  thematic index about crystals from reference/combinat/ to
  reference/combinat/crystals. This will ease the job of Reorganization of combinatorics documentation #14582.

• It's more friendly to documentation lookup using introspection

• It's more automatic; there are less chances to forget adding a file
  in the documentation which hit us often in the past.

• It enforces including all files in the documentation.

• Writing the thematic indexes as plain lists (rather than toctrees)
  is more flexible:

  • one can e.g. choose to point to the main class in a file rather
    than the full file.

  • one can focus on the user feature and not reference technical
    modules (they appear in the full module list anyway)

  • one can point to related things elsewhere in the source code

TODO

• Proof reading

• Checking that the links are functional

• Handle the various TODO's left in the indexes (typically about
  choosing the right entry points for each module)

  Postponed to a later ticket, since those are further enhancements
  not directly related to this ticket. It's just that, while browsing
  through the indexes suggested them to me.

• Finish automatizing the building of module_list.rst.

  Postponed to Automatic generation of the module list in the Sphinx documentation for sage.combinat #17421

• Sphinx issue: 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.

  For now, we stick to the class name for now until we find a good way
  to do this with Sphinx.

• Sphinx issue: how to crossrefs documents in the thematic tutorial.

  For now we use a workaround.

• Sphinx issue: homogeneous styles for the index links

  The style used by Sphinx depends on the type of the link; this makes
  the indexes look non homogeneous. See what we can do here. This is
  purely about style rather than content, hence postponed to a later
  ticket.

• Sphinx issue: latex support in :ref:

  When the title of a module contains some latex, it gets displayed
  properly in tocrefs, but not in :ref's. We had a look with
  Florent, and fixing this would require some fiddling with Sphinx's
  internals (the latex chunks are already stripped away in the
  crossref database!). Hence postponed for later as fixing this won't
  require changing the documentation sources.

Depends on #16058
Depends on #17189

CC: @sagetrac-sage-combinat @nathanncohen @tscrim @anneschilling @videlec

Component: documentation

Keywords: thematic index, quickref

Author: Nicolas M. Thiéry, Jean-Pierre Flori

Branch: 823c116

Reviewer: Anne Schilling, Nathann Cohen

Issue created by migration from https://trac.sagemath.org/ticket/16256