0

I need Sphinx autosummary extension to generate stub using :toctree: generated/ but I also want to prevent TOC entries from appearing in the HTML sidebar. Consider following docstring:

MySubPackage (mypackage.mysubpackage)
=====================================

Some Title
----------

.. currentmodule:: mypackage.mysubpackage

Some description


.. toctree::
   :hidden:
   :maxdepth: 1

   mypackage.mysubpackage.mysubsubpackage1
   mypackage.mysubpackage.mysubsubpackage2

Sub-Packages
------------

.. autosummary::
   :toctree: generated/

   mysubsubpackage1
   mysubsubpackage2

Each subsubpackage contain further private subsubsubpackages with classes and methods that are exposed in the docstring of subsubpackage's __init__.py file. The autosummary successfully generates stub files for all classes and functions in these subsubpackages but do not generate stub .rst files for intermediate packages. In the end, I am left with missing stub files without which neither TOC entries are present nor module path for classes and methods of subsubsubpackages. Using Sphinx's .. toctree:: directive solve the half of the problem by generating intermediate stub files. However, I end up with duplicated entries in the sidebar TOC. All I need is to either make autosummary to generate intermediate stub files or use some kind of option for autosummary like :hiddentoc: so that it keeps the generating stub files but not adding to entries to the TOC. I am relatively new to Sphinx and I try to automate the documentation generation process using only docstrings.

Thanks a lot in advance!

mmtechslv
  • 126
  • 1
  • 3
  • `:hidden:` hides links from the document or sidebar. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree – Steve Piercy Jun 26 '21 at 07:03

1 Answers1

1

Problem solved! For anyone who had similar issues, please read on.

The problem was caused due to repeated usage of :toctree: generated/ option in __init__.py files of sub-packages. It was causing autosummary extension to create nested /generated/generated/.. directories so it was not able to locate the *.stub files. After removing the output directory path and leaving it as simply :toctree:, the problem was solved and there was no need to use additional .. toctree:: along with .. autosummary:: directive.

mmtechslv
  • 126
  • 1
  • 3