#16256: Reorganize the documentation indexes into src/sage/combinat
-------------------------------------+-------------------------------------
Reporter: nthiery | Owner:
Type: enhancement | Status: needs_info
Priority: major | Milestone: sage-6.4
Component: documentation | Resolution:
Keywords: combinatorics, | Merged in:
thematic index, quickref | Reviewers:
Authors: Nicolas M. Thiéry | Work issues: gather comments by
Report Upstream: N/A | showing it around, and work on the
Branch: | listed TODO's
u/nthiery/reorganize_the_documentation_indexes_into_src_sage_combinat|
Commit:
Dependencies: #16058 | b3b708b629752a5eee482b62ba89aa0f918c2cc3
| Stopgaps:
-------------------------------------+-------------------------------------
Old description:
> 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.
>
> - 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`. 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
>
> - 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.
New description:
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.
- 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`. 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:
- confirm that this is the right approach
- 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.
--
Comment (by nthiery):
Hi Jean-Pierre,
Catching up with sage-trac e-mails ... sorry I had missed this one.
Replying to [comment:16 jpflori]:
> What needs to be done here?
> Building the combinat doc is one of the bottleneck on my machines, so
this ticket is highly wanted.
This ticket just reorganizes the documentation so that things get
grouped nicely by sage module. But it should make it trivial to split
the documentation on top of it in #14582.
Where you could help:
- Giving your point of view on the approach taken here.
- If you have already played with splitting sphinx documents, giving
me a hand for #14582
- And of course proofreading if you feel like it :-)
Cheers,
Nicolas
--
Ticket URL: <http://trac.sagemath.org/ticket/16256#comment:22>
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.
