#16256: Reorganize the documentation indexes into src/sage/combinat
-------------------------------------+-------------------------------------
Reporter: nthiery | Owner:
Type: enhancement | Status: needs_review
Priority: major | Milestone: sage-6.4
Component: documentation | Resolution:
Keywords: combinatorics, | Merged in:
thematic index, quickref | Reviewers:
Authors: Nicolas M. Thiéry | Work issues: Fix sphinx issues.
Report Upstream: N/A | Commit:
Branch: | 2252c4453b5788a3c44fe05100fc0a9f93ea6919
u/nthiery/reorganize_the_documentation_indexes_into_src_sage_combinat|
Stopgaps:
Dependencies: #16058 |
-------------------------------------+-------------------------------------
Description changed by nthiery:
Old description:
> == 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 #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 ==
>
> - Sphinx issue to be investigated: currently `make doc` fails upon the
> first pass of the compilation of the reference manual, complaining about
> missing link for `sage.coding`. Reruning `make doc` solves the problem.
>
> - confirm that this is the right approach
>
> - proof reading
>
> - choosing the right entry points for each module
>
> - checking that the links are functional
>
> - here or in a later ticket: finish automatizing the building of
> module_list.rst.
>
> first attempt, complaining about a broken link. One need to rerun
> it, and then the link is failed. This is probably just a glitch in
> how warnings are reported during the first pass of the reference
> manual compilation, but needs to be fixed before this ticket goes
> in.
>
> - Sphinx issue to be investigated: 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. It might be ok to stick to the class name for now until
> we find a good way to do this with Sphinx.
>
> - Sphinx issue to be investigated: how to crossrefs documents in the
> thematic tutorial. If there is no immediate way, it's possible to
> make a workaround for now.
New description:
== 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 #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
- 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)
Could be 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.
Could be postponed to a later ticket.
- Sphinx issue to be investigated: currently `make doc` fails upon the
first attempt, complaining about a broken link for
`sage.coding`. One need to rerun it, and then the link is
failed. This is probably just a glitch in how warnings are reported
during the first pass of the reference manual compilation, but needs
to be fixed before this ticket goes in.
- Sphinx issue to be investigated: 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. It might be ok to stick to the class name for now until
we find a good way to do this with Sphinx.
- Sphinx issue to be investigated: how to crossrefs documents in the
thematic tutorial. For now we use a workaround.
--
--
Ticket URL: <http://trac.sagemath.org/ticket/16256#comment:50>
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.
