Is automatic documentation from doctests a thing?

[aska...@gmail.com]

Hi,

We are working on a package on Geometric Invariant Theory and while writing up the documentation and seeing what other people did, I have noticed that the documentation for the Weyl Group library:

https://doc.sagemath.org/html/en/reference/combinat/sage/combinat/root_system/weyl_group.html#

seems to be automatically generated from the code:

https://github.com/sagemath/sage/blob/develop/src/sage/combinat/root_system/weyl_group.py

I was wondering if there is an automated way to do this (e.g. if written in the write format, to run some command or script that generates the html/pdf). If so, if there is a guide somewhere that explains the format conventions?

Many thanks,

Jesus

[John H Palmieri]

The format is explained at https://doc.sagemath.org/html/en/developer/coding_basics.html#documentation-strings. Files in the Sage library are included in the documentation if they are cited in one of the files src/doc/en/reference/MODULE/index.rst. Many of those references are explicitly in those files: look at src/doc/en/reference/curves/index.rst. The file src/doc/en/reference/combinat/index.rst, which is relevant to combinat/root_system/weyl_group, is a bit different — it includes a separate file which lists each file to be included.

With this in place, all of those files are automatically included when building the reference manual.

--

John

[Dima Pasechnik]

To add a generic Python explainer: generation of documentation from docstrings and function/class signatures is normally done by a Python package sphinx, and Sage is not much of an exception to it (although it's accumulated a lot of outdated "improvements" to it, which we ought to streamline as soon as we can).