能否让Sphinx apidoc自动拆分超大型模块为多页文档？

我正在使用Sphinx搭配autodoc为一个包含约1000个类的超大型遗留Python模块生成文档。生成的HTML文档查看体验极差，还经常导致浏览器页面崩溃。请问是否有插件或设置可以让sphinx-apidoc自动将生成的文档拆分为多页（例如每页最多50个类）？

更新： 或者是否有人知道可拆分任意现有Sphinx文档的通用插件？

我的源RST文件结构非常基础：

示例index.rst

Index
=====

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

   about
   models

示例models.rst

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

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

Submodules
----------

.. toctree::
   :maxdepth: 4

   models.contractV1

示例models.contractV1.rst

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

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

其中models/contractV1.py就是那个包含约1000个类的超大型模块。目前由于遗留代码问题，我无法手动将该模块拆分为多个文件。请问是否有办法让Sphinx自动完成拆分，同时保留所有跨链接？

1. 自定义脚本拆分模块文档 #

直接修改sphinx-apidoc的生成逻辑，或者写一个独立脚本，将单个模块的类按数量分组，生成多个RST文件，每个文件只渲染指定数量的类：

• 用Python的inspect模块导入目标模块，获取所有类对象，按50个一组拆分。
• 为每组生成对应的RST文件，比如models.contractV1_part1.rst、models.contractV1_part2.rst，每个文件的内容类似：

  models.contractV1 (Part 1)
  ==========================
  
  .. automodule:: models.contractV1
     :members: ClassA, ClassB, ..., ClassZ
     :undoc-members:
     :show-inheritance:
  

• 更新models.rst里的toctree，替换原来的models.contractV1为这些拆分后的文件。

这种方法能精准控制每页的类数量，且完全保留autodoc的跨链接功能，因为所有类还是指向原模块的定义。

2. 编写Sphinx扩展实现自动拆分 #

如果需要通用的页面拆分能力，可以写一个简单的Sphinx扩展，在文档构建阶段处理大型页面：

• 监听Sphinx的html-page-context事件，当检测到某个页面的内容过大（比如通过统计类的数量，或者HTML内容长度），将内容拆分为多个子页面。
• 为每个子页面生成新的HTML文件，同时更新原页面的toctree，添加指向子页面的链接，确保跨链接仍然有效。
• 扩展核心逻辑是解析原页面的AST，拆分类的节点，生成新的文档树节点，再渲染为独立页面。

3. 过渡方案：优化单页面显示（非多页，但缓解崩溃问题） #

如果暂时无法实现多页拆分，可以先调整autodoc的参数优化单页面体验：

• 使用:members:参数指定类的范围，按字母分组生成多个小节，比如:members: ClassA*、:members: ClassB*，在同一个页面内分块显示。
• 启用sphinx_togglebutton插件，将每个类的详情设为可折叠状态，减少页面初始加载的DOM元素数量，降低浏览器崩溃概率。

内容的提问来源于stack exchange，提问作者shomeax