Sphinx api-doc 没有将包放在一起

Question

背景

我的代码结构如下：

.
└── 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（withautodoc）我运行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 中引用它们。我该如何解决？

Answer 1

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

升级到 sphinx 1.7.6 解决了它。

Sphinx api-doc 没有将包放在一起

Sphinx api-doc not putting packages together

python

python-sphinx

sphinx-apidoc

背景

问题来了