Skip to content

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

@nthiery

Description

@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.

CC: @nathanncohen @anneschilling @jpflori @mezzarobba

Component: documentation

Issue created by migration from https://trac.sagemath.org/ticket/17421

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions