Hierarchical documentation in Sphix

Question

I am trying to generate a hierachical documentation in Sphinx.

I would like the following structure:

Introduction
Quick start
Weather API (one general page + 2 subpages)
  Temperature
  Humidity
Sky API (one general page + 3 subpages)
  Planets
  Stars
  Satellites
Future API (one page is enough for this)

Assuming that there is one file per each line in the above TOC what should I do to achieve this?

I tried to include one or more .. toctree:: directives into the top index file, but the results seem to be quite random.

score 2 · Accepted Answer · answered Feb 13 '19 at 19:51

2

Create a directory and file structure that aligns with the following toctree entries, but the actual file names are appended with the .rst suffix.

.. toctree::

    introduction
    quick_start
    weather_api/index
    weather_api/temperature
    weather_api/humidity
    sky_api/index
    sky_api/planets
    sky_api/stars
    sky_api/satellites
    future_api/index

We do this in a part of Pyramid's documentation, although we also globbing because the order of the files is not important. Your order appears to have importance, so listing them in your desired order is necessary.

answered Feb 13 '19 at 19:51

Steve Piercy

13,693
1
44
57

And I assume I must use the proper heading styles in the file (say ### for level 1 in weather_api/index.rst, and === for level 2 in temperature.rst and humidity.rst) – Jirka Feb 13 '19 at 21:42
1

You can do whatever you want, but... IMO, headings should be consistent throughout your documentation. Create a style guide and follow it. That said, the suggested heading levels are documented at: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections – Steve Piercy Feb 14 '19 at 02:58

Hierarchical documentation in Sphix

1 Answers1