python - 制作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 文件包含文档字符串。

在使用非常标准的选项(扩展名 autodoc 和 intersphinx)执行 sphinx-quickstart 之后。没有分开的源目录和构建目录。添加 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了。类名的前缀。

无论如何对我有用 :-)