使用sphinx构建文档的第一步

Question

我正试图用sphinx为python项目构建文档，但我不知道如何去做。在

起初，我的项目在这个文件夹中：

(scientific_python_2_7) lpuggini@lpuggini-T3420:~/docs$ ls ~/mlp/trunk/
applearning                  clean_only.sh  mlearncnepack     SecurityReport
build_only_docker.sh         collection     mlearn.egg-info   setup.py
build_only.sh                common         peers_peak        transaction_tracking
build.sh                     iplearning     requirements.txt  uba_sam_integration
clean_checkout_and_build.sh  jenkins        scripts           user_behaviour
(scientific_python_2_7) lpuggini@lpuggini-T3420:~/docs$ 

这里的大多数文件都是包含python代码的文件夹。这个项目相当大。在

根据一些教程，我使用默认设置安装了sphinx。 作为：

^{pr2}$

之后，我将conf.py文件的第一行编辑为

# -- 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('/home/local/CORVIL/lpuggini/mlp/trunk/'))


# -- Project information -----------------------------------------------------

project = u'mlp'
copyright = u'2018, luca'
author = u'luca'

然后：

(scientific_python_2_7) lpuggini@lpuggini-T3420:~/docs$ make html
Running Sphinx v1.7.2
making output directory...
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index                                                                          
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                                           
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.

The HTML pages are in _build/html.

之后，如果我在_build中打开htmls文件，它们不包含对我的trunk代码的任何引用。在

我想知道我错过了什么步骤，或者我应该怎么做。在

Answer 1

斯芬克斯不像JavaDoc那样工作。你必须实际编写文档。有支持使用autodoc扩展从源代码中提取文档，但即使这样，我也不会像JavaDoc那样使用它，而是编写文档并有选择地从源代码中提取文档，以避免在Python源代码和文档源代码中重复文本。在