时间戳

首页 > 解决方案 > 使用 Sphinx 从 docstring 生成文档

python - 使用 Sphinx 从 docstring 生成文档

问题描述

我的项目具有以下结构：

my_project
├── README.md
├── docs
│   ├── Makefile
│   ├── build
│   │   ├── doctrees
│   │   └── html
│   ├── make.bat
│   ├── output-docs
│   │   ├── _sources
│   │   ├── _static
│   │   ├── index.html
│   │   ├── my_project.html
│   │   ├── modules.html
│   │   └── ...
│   └── source
│       ├── _static
│       ├── _templates
│       ├── conf.py
│       ├── config_parser.rst
│       ├── index.rst
│       ├── my_project.rst
│       └── modules.rst
├── input
│   ├── a.csv
│   └── b.csv
├── my_project
│   ├── config.yml
│   ├── config_parser.py
│   ├── my_project.py
│   └── utils
│       └── my_utility.py
...

我有与各种functionsinmy_project.py和my_utility.py. 我想使用Sphinx. 所以我做了以下事情：

mkdir docs
cd docs
sphinx-quickstart

我提供了所要求的选项（作者、版本等）。然后我修改source/config.py如下（我只包括修改）：

import os
import sys
sys.path.insert(0, os.path.abspath('../../'))

extensions = ['recommonmark', 'sphinx.ext.autodoc']

然后我用sphinx-apidoc了，后面是一个sphinx-build。以下是代码（这是在docs文件夹中运行的）：

sphinx-apidoc -f -o source/ ../my_project
sphinx-build source output_docs

但是我得到了几个错误：

reading sources... [100%] config_parser
WARNING: autodoc: failed to import module 'config_parser'; the following exception was raised:
No module named 'config_parser'
looking for now-outdated files... none found
pickling environment... done

checking consistency... /Users/my_user/Projects/my_project/docs/source/modules.rst: WARNING: document isn't included in any toctree

此外，HTML 文档包含在output-docs. 但是当我打开时index.html，我看到了my_project，但没有包含任何模块或文档字符串。

我不知道我错过了什么。我浏览了一些文档，还有一些问题，比如Generate sphinx docu from docstrings not working，但我想我错过了一些重要的东西。任何帮助都会很棒。

编辑 1：

正如@Steve 所建议的，我在 and 中添加__init__.py了my_project/my_project一个my_project/my_project/utils。现在，我正在获取为functionsinmy_project/my_project/utils/my_utility.py和my_project/my_project/config_parser.py. 但是，仍然缺少my_project/my_project/my_project.py.

我认为合理的原因可能是：

  1. my_project.py有这个main功能。所以我注释掉了这个main函数，但仍然没有生成文档。
  2. my_project.py与其父目录同名，my_project. 所以我重命名了它，但仍然没有生成文档。

任何有关如何取得进展的指南都会非常有帮助。

标签： pythonpython-sphinx

解决方案

推荐阅读