使用Sphinx从文档字符串生成文档

时间:2020-08-19 12:07:08

标签: python python-sphinx

我的项目具有以下结构:

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
...

我在functionsmy_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的建议,我在__init__.pymy_project/my_project上都添加了my_project/my_project/utils。现在,我正在functionsmy_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具有相同的名称。因此,我将其重命名,但仍未生成文档。

任何有关进步的指南都将非常有帮助。

0 个答案:

没有答案