从文档字符串生成 sphinx 文档不起作用

Question

我有一个具有以下结构的项目（我想保留）：

my_project
├── build  # here is where sphinx should dump into
├── requirements.txt
├── make.bat
├── Makefile
├── ...  # more config files
├── doc  # this is where I want sphinx files to live
│   ├── conf.py
│   └── index.rst
├── src
│   └── my_project
│       ├── __init__.py
│       ├── module_1
│       │   ├── __init__.py
│       │   └── ...
│       └── util
│           ├── __init__.py
│           └── ...
└── tests
    ├── module_1
    │   ├── __init__.py
    │   └── ...  # testing module 1
    └── util
        ├── __init__.py
        └── ...  # testing util stuff

我重新创建了on github，可以通过在里面执行my_setup.sh来重新创建结果。

我想从文档字符串构建文档。我使用 sphinx 的快速入门来生成必要的配置，但是当我调用 make hmtl 时，生成的文档不包含来自我的源代码的任何文档字符串，即 my_project/src/my_project 中的所有内容。 Sphinx 的文档有点压倒性，因为我觉得我正在尝试设置一些非常基本的东西。

配置文件中的相关信息（如果我忘记了重要内容，请告诉我）：

生成文件

SPHINXOPTS    =
SPHINXBUILD   = sphinx-build
SPHINXPROJ    = my_project
SOURCEDIR     = doc
BUILDDIR      = build
...

ma​​ke.bat

set SOURCEDIR=doc
set BUILDDIR=build
set SPHINXPROJ=my_project
...

conf.py

import os
import sys
sys.path.insert(0, os.path.abspath('../src/my_project'))
...
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
]
...

---

我也试过this，但它首先将一堆构建文件放入doc，我宁愿不在那里，而且它也没有找到任何模块（通过省略@987654334来修复@参数）：

$ sphinx-apidoc -F -o doc/ src/my_project/
$ cd doc
$ make html
Running Sphinx v1.7.2
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 2 changed, 0 removed
reading sources... [100%] my_project.util                                                                                                                                                                                  
WARNING: autodoc: failed to import module 'my_project'; the following exception was raised:
No module named 'my_project'
WARNING: autodoc: failed to import module 'my_project.util.test_file'; the following exception was raised:
No module named 'my_project'
WARNING: autodoc: failed to import module 'my_project.util'; the following exception was raised:
No module named 'my_project'
looking for now-outdated files... none found
pickling environment... done
checking consistency... /home/arne/workspace/git/my_project/doc/my_project.rst: WARNING: document isn\'t included in any toctree
done
preparing documents... done
writing output... [100%] my_project.util                                                                                                                                                                                   
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 4 warnings.

Answer 1

您的 MCVE 存在一些问题。

1. rST 源文件不得位于输出目录build，而应位于文档源目录docs。您应该这样做：sphinx-apidoc -o docs src/my_project。

2. 正如@mzjn 提到的，您需要取消注释并在您的conf.py 中添加一些行以解决WARNING: autodoc: failed to import module 错误。

   # -- Path setup --------------------------------------------------------------
   
   # 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('.'))
   sys.path.insert(0, os.path.abspath('../src/'))
   

在这两项更改之后，我能够使用其 API 成功构建您的文档。