#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 | 80d54890d91a024dfdd45a6d3eed4b8410dc25b5
Branch: | Stopgaps:
u/nthiery/ticket/16256 |
Dependencies: #16058, #17189 |
-------------------------------------+-------------------------------------
Changes (by nthiery):
* commit: 7b753a2c64af971fc37d1fffa8f95e6fac1e0438 =>
80d54890d91a024dfdd45a6d3eed4b8410dc25b5
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 a later ticket.
>
> - 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.
>
> For now, we 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.
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.
--
Comment:
New commits:
||[http://git.sagemath.org/sage.git/commit/?id=80d54890d91a024dfdd45a6d3eed4b8410dc25b5
80d5489]||{{{16256: Module List -> Comprehensive Module List and link to
trac ticket}}}||
--
Ticket URL: <http://trac.sagemath.org/ticket/16256#comment:97>
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.
