nthiery
commented
10 years ago Description changed:
---
+++
@@ -1,16 +1,16 @@
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?
+ `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.
+- 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 sage/combinat/ are now included in the reference manual
+- All p/cython files in `src/sage/combinat/` are now included in the reference manual
- Improved thematic indexes
6bdad4c1-1e26-4f2f-a442-a01a2292c181
jpflori
7ed8c4ca-6d56-4ae9-953a-41e42b4ed313
anneschilling
Goal: reorganize the documentation indexes into src/sage/combinat
For example, the thematic index
src/doc/en/reference/combinat/crystals.rstis now in:src/sage/combinat/crystals/__init__.pyand is accessible throughsage.combinat.crystals?(potential variant: put it in all.py)
What's left in
doc/en/reference/combinatcan 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 manualImproved 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/crystalsin its own document required to move the thematic index about crystals fromreference/combinat/toreference/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.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:
823c116Reviewer: Anne Schilling, Nathann Cohen
Issue created by migration from https://trac.sagemath.org/ticket/16256