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来重新创建结果。

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

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

生成文件

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

MAKE.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，我宁愿不在那里，也没有找到任何模块（由省略-F参数）：

$ 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存在一些问题。

rST源文件不得驻留在输出目录build中，并且应位于文档源目录docs中。你应该这样做：sphinx-apidoc -o docs src/my_project。

正如@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成功构建您的文档。

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

1 个答案: