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

Question

（替代描述可以是 'how to rename a sphinx-autodoc package name?'）

在 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

returns 如下文档： you can ignore the red.

问题

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

Answer 1

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

在此issue for Pyramid and examples in hupper and pyramid_retry中解释了另一个例子。但是，您仍然会有 MyPythonProject/src/MyPythonProject，虽然更笨重但可能不会那么难看。

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

Answer 2

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

因此，通过在 docs/conf.py:

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

并在您的狮身人面像中 index.rst 相应地更改自动模块::。

那样的话，你就没有那个src了。 class 名字的前缀。

无论如何对我有用:-)

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

How to ignore 'src' directory in python project when making sphinx autodoc

python

setup.py

python-sphinx

autodoc

问题