從文檔字符串生成獅身人面像文檔

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

我在github上重新創建了它，可以通過在其中執行my_setup.sh來重新創建結果。

我想從文檔字符串構建文檔。 我使用了sphinx的快速入門來生成必要的配置，但是當我調用make hmtl ，生成的文檔不包含源代碼中的任何文檔字符串，即my_project/src/my_project所有文檔字符串。 Sphinx的文檔處理有點讓人不知所措，因為我覺得我正在嘗試建立一些非常基本的東西。

配置文件中的相關信息（請告訴我是否忘記了重要信息）：

Makefile文件

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',
]
...

---

我也嘗試過此方法，但是它首先將一堆我不希望在其中的構建文件放到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存在幾個問題。

1. rST源文件不得駐留在輸出目錄內部build ，而應位於docs源目錄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成功構建您的文檔。