时间戳

首页 > 解决方案 > 如何在 sphinx-apidoc 中包含几个子目录？

python-sphinx - 如何在 sphinx-apidoc 中包含几个子目录？

问题描述

问题

我正在尝试为包含许多子目录的 Python 项目构建文档。我正在尝试使用sphinx-apidoc使过程无缝。然而，尽管我尽了最大努力，我还是无法处理子目录中的代码。我在这里遵循了 YouTube 上的一个很棒的简短教程，并且效果很好。为了模拟我一直遇到的问题，我将其中一个文件放在一个can_it_handle_folders目录中，如下所示。

spamfilter-py
│   __init__.py  (**)
│   readme.md
│   sample.py
│   spamfilter.py
│   token.py
├───can_it_handle_folders
│       __init__.py
│       test_spamfilter.py
├───docs
│   ├───build
│   │   └───html
│   └───source
│       ├───conf.py
│       ├───index.rst
│       ├───modules.rst
│       ├───sample.rst
│       ├───spamfilter.rst
│       ├───token.rst
│       ├───spamfilter-py.test_spamfilter.rst
│       └───html
...

我转到docs目录并运行sphinx-apidoc -o . ..以根据根spamfilter目录生成 .rst 文件。我已将以下行添加到conf.py：

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

我生成的modules.rst看起来像：

spamfilter-py
=============

.. toctree::
   :maxdepth: 4

   sample
   spamfilter
   token

目录中任何内容的 htmlcan_it_handle_folders都不会生成。如果我尝试添加can_it_handle_folders/test_spamfilter到目录树，我会得到一个toctree contains reference to nonexisting document 'can_it_handle_folders/test_spamfilter'错误。

问题

我希望test_spamfilter模块显示在生成的 html 中。我该怎么做呢？设置它的最佳方法是什么？

更新：它是初始化文件

我已经隔离了这个问题，它似乎__init__.py在根目录中（上面标有**）。我不知道该如何处理。如果我删除它，狮身人面像会完全按照我想要的方式工作。如果我保留它，问题就变成了这里。看来这一定是sys.path. 对于每个文件，这是我得到的错误：

WARNING: invalid signature for automodule ('spamfilter-py.can_it_handle_folders')
WARNING: don't know which module to import for autodocumenting 'spamfilter-py.can_it_handle_folders' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)

我在conf.py文件中尝试了以下内容：

所有这些都导致了上述相同的错误消息。sphinx-apidoc -o ./source ../..除了sphinx-apidoc -o ./source ..上面的每个路径之外，我还尝试过运行。可能是什么问题？我知道这一定是一些小的配置。

语境

我是 Sphinx 的绝对初学者。我试图阅读文档，但它没有解决这个问题。我尝试了许多我认为显然不正确的事情。如果没有简单的答案，我会在这里添加我的尝试。我知道还有其他关于此的堆栈溢出问题，但它们不是最近的并且没有帮助。

包含的文件：

Welcome to j's documentation!
=============================

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

   modules

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

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


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

project = 'j'
copyright = '2020, k'
author = 'k'


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx.ext.autodoc'
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []


# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

spamfilter\-py package
======================

Subpackages
-----------

.. toctree::
   :maxdepth: 4

   spamfilter-py.can_it_handle_folders

Submodules
----------

spamfilter\-py.sample module
----------------------------

.. automodule:: spamfilter-py.sample
   :members:
   :undoc-members:
   :show-inheritance:

spamfilter\-py.spamfilter module
--------------------------------

.. automodule:: spamfilter-py.spamfilter
   :members:
   :undoc-members:
   :show-inheritance:

spamfilter\-py.token module
---------------------------

.. automodule:: spamfilter-py.token
   :members:
   :undoc-members:
   :show-inheritance:

Module contents
---------------

.. automodule:: spamfilter-py
   :members:
   :undoc-members:
   :show-inheritance:

这是文档的样子： 没有方法或参数

标签： python-sphinxrestructuredtextsphinx-apidoc

解决方案

推荐阅读