如何不使用automodule从Python项目生成对应类、模块的.rst文件？

核心实现逻辑 #

不依赖automodule的自动扫描、自动生成文档能力，通过和源码路径、Python对象全限定名一一对应的rST文件命名规则，结合Sphinx Python域的原生手写指令编写文档内容，最终生成可正常编译的HTML文档。整个过程没有调用automodule拉取源码注释的逻辑，所有rST的写法、内容都是完全可控、可查看的。

参考项目结构示例 #

先对齐常见的多包Python项目结构，作为后续rST文件映射的参照：

my_project/
├── core/                # 顶层Python包
│   ├── __init__.py
│   ├── data_loader.py   # 具体Python模块
│   │   └── class CSVLoader:  # 模块内的公开类
│   └── model/           # 子Python包
│       ├── __init__.py
│       ├── trainer.py   # 具体Python模块
│       └── evaluator.py # 具体Python模块
└── utils/               # 第二个顶层Python包
    ├── __init__.py
    └── logger.py        # 具体Python模块

不同层级对象对应的rST实际写法 #

所有rST文件都按照与Python对象全限定名严格对应的规则存放，路径与源码包结构完全对齐，以下是每类对象对应的实际可运行的rST内容：

对应Python包的rST文件 #

以core顶层包为例，对应的rST文件为core/index.rst，内容示例：

core 核心包
===========

本包承载项目的核心数据处理、模型训练全流程能力。

.. py:module:: core

子模块导航
----------

.. toctree::
   :maxdepth: 1

   core/data_loader
   core/model/trainer
   core/model/evaluator

对应具体Python模块的rST文件 #

以core.data_loader模块为例，对应的rST文件为core/data_loader.rst，内容示例：

core.data_loader 模块
======================

本模块实现多格式数据源的加载逻辑，统一输出标准化的张量数据格式。

.. py:module:: core.data_loader

模块级常量
----------
.. py:data:: DEFAULT_ENCODING
   :value: 'utf-8'

   加载文本类文件时默认使用的字符编码

公开类导航
----------

.. toctree::
   :maxdepth: 1

   core/data_loader/CSVLoader

对应单个类的rST文件 #

以core.data_loader.CSVLoader类为例，对应的rST文件为core/data_loader/CSVLoader.rst，内容示例：

CSVLoader 类
=============

CSV格式表格数据的专用加载器实现

.. py:class:: CSVLoader(file_path: str, has_header: bool = True)

   初始化参数
   ----------
   :param file_path: 待加载的CSV文件全路径
   :type file_path: str
   :param has_header: 是否将文件首行识别为列名，默认为True
   :type has_header: bool

   公开方法
   --------
   .. py:method:: load() -> pandas.DataFrame

      执行文件解析逻辑，返回加载完成的结构化数据
      :rtype: pandas.DataFrame

   .. py:method:: set_column_type(schema: dict) -> None

      手动指定列数据类型，覆盖自动识别结果
      :param schema: 列名与对应数据类型的映射字典
      :type schema: dict

严格一一映射的落地规则 #

为了确保rST文件和模块、类完全对应，可遵循以下规则：

• 路径对齐规则：rST文件的存放路径和源码的包路径完全一致，不做额外的目录层级跳转
• 命名规则：包对应的rST统一命名为index.rst；模块对应的rST用模块名命名；类对应的rST用类名命名
• 导航关联规则：上层对象的rST内，通过toctree把下属的所有子对象rST纳入导航链路，不需要自动扫描源码生成导航
• 指令绑定规则：每个rST内通过Sphinx Python域的py:module::、py:class::、py:method::指令，和源码中的对应Python对象做锚点绑定，确保跳转链接正常

Sphinx配置注意事项 #

完全不使用automodule的前提下，只需要保留基础的文档解析配置即可：

• 不需要在扩展列表中引入sphinx.ext.autodoc，避免触发自动生成文档的逻辑
• 可选引入sphinx.ext.napoleon 支持常用的注释格式解析，sphinx.ext.viewcode 支持源码跳转链接生成
• 确保toctree配置的文件路径和实际存放的rST路径完全匹配，避免编译时的文件找不到报错

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