Display directly first element of Sphinx index.rst's toctree instead of a blank page

380 Views Asked by At

I have a Python package (https://github.com/frannerin/AlloViz)'s documentation (https://alloviz.readthedocs.io/) with the following structure:

AlloViz/docs/source
│   conf.py
│   index.rst
│   README.rst
│
└───API
    │   index.rst
    │   generate.rst # only has autosummary directive that is passed to autosummary_generate
    │                # in the conf.py file to generate the .rst files in the generated/ folder 
    │
    └───generated # Files generated automatically by autosummary extension with NumPy's templates
        │   AlloViz.rst
        │   AlloViz.Protein.rst # Protein class
        │   AlloViz.Protein.calculate.rst # Protein class method
            ...
        │   AlloViz.Delta.rst # Delta class

I am using Read the Docs to build and host my documentation, using numpydoc, autosummary (using NumPy's .rst templates) and the pydata-sphinx-theme. Currently, I have three headers (three elements in the main index.rst file's toctree) in my documentation:

Screenshot of https://alloviz.readthedocs.io/ headers

Then, source/API/index.rst looks like this:

API reference
=============

.. toctree::
   :caption: AlloViz
   :maxdepth: 2
   :hidden:

   AlloViz.Protein <generated/AlloViz.Protein>
   AlloViz.Delta <generated/AlloViz.Delta>

and it renders a page (https://alloviz.readthedocs.io/en/latest/API/index.html) that is empty:

Screenshot of https://alloviz.readthedocs.io/en/latest/API/index.html

But I would like that, when clicking to the "API reference" header at the top of the page, it showed directly the page corresponding to the AlloViz.Protein documentation (https://alloviz.readthedocs.io/en/latest/API/generated/AlloViz.Protein.html), which corresponds to a file generated by autosummary inside the generated/ folder:

Screenshot of https://alloviz.readthedocs.io/en/latest/API/generated/AlloViz.Protein.html

Using an .. include directive in the API/index.rst file to include the contents of the API/generated/AlloViz.Protein.rst file doesn't work completely because it doesn't inherit the latter file's toctree inside it (which points to the class' methods), and also throws out warnings of duplicate members, and is just inelegant. I'm open to exploring whatever options if given some pointers!

0

There are 0 best solutions below