问题
我正在尝试为包含许多子目录的 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
文件中尝试了以下内容:
sys.path.insert(0, os.path.abspath(os.path.join('..')))
sys.path.insert(0, os.path.abspath(os.path.join('..', '..')))
sys.path.insert(0, os.path.abspath(os.path.join('..', '..', '..')))
所有这些都导致了上述相同的错误消息。sphinx-apidoc -o ./source ../..
除了sphinx-apidoc -o ./source ..
上面的每个路径之外,我还尝试过运行。可能是什么问题?我知道这一定是一些小的配置。
语境
我是 Sphinx 的绝对初学者。我试图阅读文档,但它没有解决这个问题。我尝试了许多我认为显然不正确的事情。如果没有简单的答案,我会在这里添加我的尝试。我知道还有其他关于此的堆栈溢出问题,但它们不是最近的并且没有帮助。
- 使用 PowerShell 执行命令的 Windows 10 计算机
包含的文件:
- 索引.rst
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.rst:
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: