#16256: Reorganize the documentation indexes into src/sage/combinat
-------------------------------------+-------------------------------------
Reporter: nthiery | Owner:
Type: enhancement | Status: needs_info
Priority: major | Milestone: sage-6.2
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 | d3284073bb560acb669287ef1c7208e8b384cbdd
| Stopgaps:
-------------------------------------+-------------------------------------
Description changed by nthiery:
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`.
>
> - 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:
- 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#comment:13>
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.
