Opened 8 years ago

Last modified 8 years ago

#17421 new enhancement

Automatic generation of the module list in the Sphinx documentation for sage.combinat

Reported by: Nicolas M. Thiéry Owned by:
Priority: major Milestone: sage-6.5
Component: documentation Keywords:
Cc: Nathann Cohen, Anne Schilling, Jean-Pierre Flori, Marc Mezzarobba Merged in:
Authors: Reviewers:
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Status badges

Description (last modified by Nicolas M. Thiéry)

Currently, the list of all modules to be included in the Sage reference manual needs to be maintained by hand. This is tedious, and modules often end up accidently missing in those lists. Besides, maintaining thoses lists is a common source of trivial but annoying conflicts.

#16256 includes a first step toward automatizing the process in the context of sage.combinat (see src/doc/en/reference/combinat/module_list.rst. The purpose of this ticket is to finish the automatizing. This requires some Sphinx configuration / programming.

Desirable features:

  • Sorting the list alphabetically according to the module titles rather than module names?
  • Do not flatten the module hierarchical structure.

A natural approach would be to use the :glob: feature of toctree (see http://sphinx-doc.org/markup/toctree.html). However, the globing is done on the .rst files, not on the original modules. And those .rst files are currently automatically generated only for the modules that are listed in the toctree (see ReferenceSubBuilder.get_all_included_modules in src/doc/common/builder.py). So we need to break that loop.

Change History (5)

comment:1 Changed 8 years ago by Nicolas M. Thiéry

Description: modified (diff)

comment:2 Changed 8 years ago by Nathann Cohen

Cc: Nathann Cohen added

comment:3 Changed 8 years ago by Anne Schilling

Cc: Anne Schilling added

comment:4 Changed 8 years ago by Jean-Pierre Flori

Cc: Jean-Pierre Flori added

comment:5 Changed 8 years ago by Marc Mezzarobba

Cc: Marc Mezzarobba added
Note: See TracTickets for help on using tickets.