Opened 5 years ago

Last modified 5 years ago

#17421 new enhancement

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

Reported by: nthiery Owned by:
Priority: major Milestone: sage-6.5
Component: documentation Keywords:
Cc: ncohen, aschilling, jpflori, mmezzarobba Merged in:
Authors: Reviewers:
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Description (last modified by nthiery)

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 5 years ago by nthiery

  • Description modified (diff)

comment:2 Changed 5 years ago by ncohen

  • Cc ncohen added

comment:3 Changed 5 years ago by aschilling

  • Cc aschilling added

comment:4 Changed 5 years ago by jpflori

  • Cc jpflori added

comment:5 Changed 5 years ago by mmezzarobba

  • Cc mmezzarobba added
Note: See TracTickets for help on using tickets.