#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. | Work issues:
Thiéry, Jean-Pierre Flori | Commit:
Report Upstream: N/A | f5aa239b4946392411d97f4269ef5e646e215bfc
Branch: | Stopgaps:
u/nthiery/ticket/16256 |
Dependencies: #16058, #17189 |
-------------------------------------+-------------------------------------
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 ==
>
> - 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.
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 ==
- 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.
--
--
Ticket URL: <http://trac.sagemath.org/ticket/16256#comment:101>
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.
