制作sphinx autodoc时如何忽略python项目中的'src'目录

Posted 2023-03-30

【中文标题】制作sphinx autodoc时如何忽略python项目中的\'src\'目录

【英文标题】：How to ignore 'src' directory in python project when making sphinx autodoc制作sphinx autodoc时如何忽略python项目中的'src'目录

【发布时间】：2018-03-21 18:01:02

【问题描述】：

（替代描述可以是“如何重命名 sphinx-autodoc 包名称？”）

在 Python 2.7.13 上使用 sphinx 1.7 版

---

我想使用文档字符串和sphinx-apidoc 自动创建文档。

我的项目结构如下：

myPythonProject      <- my Python package name and git repository.
|-- docs
|   |-- _build
|   |   |-- html     <- where final HTML doc is created.
|   |   
|   |-- apidocs      <- contains the autodoc created '.rst' files.
|   |-- _static
|   |-- _templates
|   |
|   | conf.py        <- 4 Sphinx doc files, auto generated with sphinx-quickstart.
|   | index.rst      <-
|   | make.rst       <-
|   | Makefile       <-
|
|
|-- src
|   | __init__.py    <- important for 'setup.py'.
|   | myModule1.py
|   | myModule2.py
|   | myModule3.py
|
| setup.py

myModule 文件包含文档字符串。

在使用非常标准的选项执行sphinx-quickstart 之后（扩展 autodoc 和 intersphinx。没有单独的源目录和构建目录。添加 make.bat 和 Makefile 文件。） 对conf.py 进行了一些小改动，我在其中取消了注释并进行了更改：

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.

import os
import sys
sys.path.insert(0, os.path.abspath('../'))

运行时： sphinx-apidoc -f -o docs/apidocs src

找到了文档字符串，但确信 src 是我的包名。它显然没有观察到我的setup.py 文件或其他东西。它确实查看了 __init__.py 但是，如果我删除它，我可以创建只有模块的文档，根本没有包。但这也是不希望的，但至少更接近。

src 的内容安装为“MyPythonProject”。因此Setup.py配置如下来安装这个包并在导入时省略'src'引用：

from setuptools import setup

setup(
    name='MyPythonProject',

    packages='MyPythonProject': 'src',
    package_dir='MyPythonProject': 'src',

（这是一种非正统的结构吗？否则我也会对 autodoc 支持的更常见的布局感兴趣。）

---

目前

sphinx-apidoc -f -o docs/apidocs src
sphinx-build -a -b html docs/ docs/_build/html

返回以下文档： you can ignore the red.

问题

如何创建显示 myPythonProject.myModule1.def1() 是文档字符串而不是 src.myModule1.def1() 的文档？

【参考方案1】：

另一种选择是在路径中包含 src 并指定不带 src 前缀的模块。

因此，通过在 docs/conf.py 中将上面的行替换为该行，将路径设置更改为 src 文件夹：

sys.path.insert(0, os.path.abspath('../src'))

并在您的 sphinx index.rst 中相应地更改 automodule::。

那样，您将没有该 src。类名的前缀。

无论如何都为我工作:-)

【讨论】：

我无法测试这个答案，但我认为这是一个不那么老套的解决方案。感谢分享！这可能是在更高版本中提供的解决方案吗？

【参考方案2】：

将src 重命名为myPythonProject。 Pyramid 是遵循这一约定的一个示例。

issue for Pyramid 中解释了另一个示例，hupper 和pyramid_retry 中的示例。但是，您仍然会拥有MyPythonProject/src/MyPythonProject，尽管它更笨拙可能不会那么难看。

最终，无论您将包含您的包的直接父目录命名为什么，都将成为该方法的 Python 点分名称的第一部分。

【讨论】：

何史蒂夫，感谢您的快速回复！这当然是一个解决方案，但是将src 目录用于项目代码不是很常见吗？正因为如此，我认为这个问题必须有一个解决方法......重命名会导致myPythonProject/myPythonProject 文件夹，我有点不喜欢。再次感谢！

非常感谢史蒂夫！因此，换句话说，它不受支持，人们使用某种变通方法来在 Sphinx 中获得正确的包命名（并且不会被它必须像这样构造的事实所困扰；））。