Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Trac #16256: Reorganize the documentation indexes into src/sage/combinat
== 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/sa ge/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 #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 #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. URL: http://trac.sagemath.org/16256 Reported by: nthiery Ticket author(s): Nicolas M. Thiéry, Jean-Pierre Flori Reviewer(s): Anne Schilling, Nathann Cohen
- Loading branch information
