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

Question

（替代描述可以是“如何重命名 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() 的文档？

Answer 1

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

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

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

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

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

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

Answer 2

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

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

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