Sphinx api-doc不将软件包放在一起

时间:2018-07-17 08:38:29

标签: python python-sphinx sphinx-apidoc

背景

我的代码具有以下结构:

.
└── my_package
    ├── __init__.py
    ├── classif
    │   ├── __init__.py
    │   ├── inference.py
    │   └── models.py
    ├── datasets
    │   ├── __init__.py
    │   └── datasets.py
    └── matching
        ├── __init__.py
        ├── elastic.py
        └── search.py

sphinx-quickstart(与autodoc)之后,我按照以下方式运行了sphinx-apidoc

sphinx-apidoc -f -o source my_package -e -M

我现在有以下文件:

.
├── Makefile
├── build
├── my_package
│   ├── __init__.py
│   ├── __pycache__
│   ├── classif
│   ├── datasets
│   └── matching
└── source
    ├── _static
    ├── _templates
    ├── conf.py
    ├── index.rst
    ├── modules.rst
    ├── my_package.classif.inference.rst
    ├── my_package.classif.models.rst
    ├── my_package.classif.rst
    ├── my_package.datasets.datasets.rst
    ├── my_package.datasets.rst
    ├── my_package.matching.elastic.rst
    ├── my_package.matching.rst
    ├── my_package.matching.search.rst
    └── my_package.rst

我还修改了conf.py以添加:

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

并将modules添加到index.rst

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   modules

# [more lines]

现在是问题所在

运行make clean ; make html后,我得到警告:

/path/to/my_package.classif.rst: WARNING: document isn't included in any toctree
/path/to/my_package.datasets.rst: WARNING: document isn't included in any toctree
/path/to/my_package.matching.rst: WARNING: document isn't included in any toctree

这很有意义,因为 sphinx-apidoc在my_package.rst 中未引用它们。我该怎么解决?

1 个答案:

答案 0 :(得分:0)

问题实际上是已知的-> https://github.com/sphinx-doc/sphinx/issues/4446

升级为狮身人面像1.7.6已解决。