I'm using Sphinx with autodoc to generate documentation for very huge Python module (about 1000 classes, don't ask me why, this is legacy code).

Resulting HTML is painful to view and regularly crashes browser page.

Is there any plugin or setting that make sphinx-apidoc automatically split generated document to several pages, say, no more than 50 classes each?

UPDATE: Or, maybe somebody knows a generic plugin to split any existing Sphinx document to pages?

source RST is pretty basic:

Example index.rst

Index
=====

.. toctree::
   :maxdepth: 2
   :caption: Title

   about
   models

example models.rst:

models package
==============

.. automodule:: models
   :members:
   :undoc-members:
   :show-inheritance:

Submodules
----------

.. toctree::
   :maxdepth: 4

   models.contractV1

example models.contractV1 rst:

models.contractV1 module
========================

.. automodule:: models.contractV1
   :members:
   :undoc-members:
   :show-inheritance:

And models/contractV1.py is that huuuuge module with around 1000 classes.

I can't split that module to several files by myself currently due to legacy code issues.

Is there anything possible to make Sphinx do it automatically, while maintaining all the cross-links and such?

I'm using Sphinx with autodoc to generate documentation for very huge Python module (about 1000 classes, don't ask me why, this is legacy code).

Resulting HTML is painful to view and regularly crashes browser page.

Is there any plugin or setting that make sphinx-apidoc automatically split generated document to several pages, say, no more than 50 classes each?

UPDATE: Or, maybe somebody knows a generic plugin to split any existing Sphinx document to pages?

source RST is pretty basic:

Example index.rst

Index
=====

.. toctree::
   :maxdepth: 2
   :caption: Title

   about
   models

example models.rst:

models package
==============

.. automodule:: models
   :members:
   :undoc-members:
   :show-inheritance:

Submodules
----------

.. toctree::
   :maxdepth: 4

   models.contractV1

example models.contractV1 rst:

models.contractV1 module
========================

.. automodule:: models.contractV1
   :members:
   :undoc-members:
   :show-inheritance:

And models/contractV1.py is that huuuuge module with around 1000 classes.

I can't split that module to several files by myself currently due to legacy code issues.

Is there anything possible to make Sphinx do it automatically, while maintaining all the cross-links and such?

• python-sphinx
• autodoc
• sphinx-apidoc

1 Answer 1

I don't think there is anything automatic for this.

The automodule directive will always document the whole module (i.e. the stuff listed in __all__. You can replace it by individual .. autoclass:: directives. That means you would have generate the .rst file yourself. Should not be too hard with a python script, e.g. like this (untesteed):

import contractV1
names = contractV1.__all__
num = 1
while names:
    page_names = names[:50]
    names = names[50:]
    text = f"""ContractV1 (page {num})\n================\n\n"""
    text = text + "\n\n".join(
        f""".. autoclass:: models.contractV1.{name}
:members:
:undoc-members:
:show-inheritance:
        """
        for name in page_names
    )
    Path(f"contractV1_page{num}.rst").write_text(text)
    num += 1
   

If your contractV1 also has non-class members, or doesn't define __all__, you'll need to use introspection (inspect builtin module) to make up the names list.

In the models.rst TOC, you need to list all the page documents individually -> left as exercise for the reader :-)