#16256: Reorganize the documentation indexes into src/sage/combinat
-------------------------+-------------------------------------------------
Reporter: nthiery | Owner:
Type: | Status: new
enhancement | Milestone: sage-6.2
Priority: major | Keywords: combinatorics, thematic
Component: | index, quickref
documentation | Authors: Nicolas M. Thiéry
Merged in: | Report Upstream: N/A
Reviewers: | Branch:
Work issues: | Dependencies: #16058
Commit: |
Stopgaps: |
-------------------------+-------------------------------------------------
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 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.
- Added (draft of) sage.combinat.quickref
End result browsable at
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. 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`.
- 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
- choosing the right entry points for each module
- 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.
- here or in a later ticket: finish automatizing the building of
module_list.rst.
This is a follow up to #16058.
--
Ticket URL: <http://trac.sagemath.org/ticket/16256>
Sage <http://www.sagemath.org>
Sage: Creating a Viable Open Source Alternative to Magma, Maple, Mathematica,
and MATLAB
--
You received this message because you are subscribed to the Google Groups
"sage-trac" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/sage-trac.
For more options, visit https://groups.google.com/d/optout.
