python - 如何为 Sphinx 正确设置项目目录

Question

我查看了许多教程和视频，其中介绍了使用 Sphinx 生成文档的过程，此时我确信我的项目结构有问题。我正在运行 Windows 10 Pro，2004；Python 3.7.9；狮身人面像 3.3.0。

sphinx_test我按照以下步骤创建了一个全新的项目来测试我的 Sphinx 技能：

1. 创建一个新的虚拟环境python -m virtualenv sphinxtest
2. 激活它sphinxtest\Scripts\activate
3. 安装 Sphinx 和要求pip install sphinx
4. 创建一个新的项目文件夹mkdir sphinx_test并导航到它cd sphinx_test
5. 为源代码和所有子模块创建子目录mkdir src
6. *.py使用随机文档字符串（nopes.py和sqrer.py）创建一些愚蠢的示例文件
7. 创建 docs 目录mkdir docs 并导航到它cd docs
8. 执行sphinx-quickstart --ext-autodoc，选择单独build的source目录
9. 修改conf.py，添加 ./src/到PATH
10. 修改index.rst，在组modules下面添加toctree：

11. sphinx-apidoc -o .\source\ ..\src\从目录内部运行docs。
12. 运行make html并获得以下信息：

Running Sphinx v3.3.0
    loading pickled environment... done
    building [mo]: targets for 0 po files that are out of date
    building [html]: targets for 2 source files that are out of date
    updating environment: 0 added, 2 changed, 0 removed
    reading sources... [100%] src
    WARNING: autodoc: failed to import module 'nopes' from module 'src'; the following exception was raised:
    No module named 'src'
    WARNING: autodoc: failed to import module 'sqrer' from module 'src'; the following exception was raised:
    No module named 'src'
    WARNING: autodoc: failed to import module 'src'; the following exception was raised:
    No module named 'src'
    looking for now-outdated files... none found
    pickling environment... done
    checking consistency... done
    preparing documents... done
    writing output... [100%] src
    generating indices... genindex done
    writing additional pages... search done
    copying static files... done
    copying extra files... done
    dumping search index in English (code: en)... done
    dumping object inventory... done
    build succeeded, 3 warnings.
    
    The HTML pages are in build\html.

这是目前的文件夹结构：

C:.
├───docs
│   │   make.bat
│   │   Makefile
│   │
│   ├───build
│   │   ├───doctrees
│   │   │       environment.pickle
│   │   │       index.doctree
│   │   │       modules.doctree
│   │   │       src.doctree
│   │   │
│   │   └───html
│   │       │   .buildinfo
│   │       │   genindex.html
│   │       │   index.html
│   │       │   modules.html
│   │       │   objects.inv
│   │       │   search.html
│   │       │   searchindex.js
│   │       │   src.html
│   │       │
│   │       ├───_sources
│   │       │       index.rst.txt
│   │       │       modules.rst.txt
│   │       │       src.rst.txt
│   │       │
│   │       └───_static
│   │               alabaster.css
│   │               basic.css
│   │               custom.css
│   │               doctools.js
│   │               documentation_options.js
│   │               file.png
│   │               jquery-3.5.1.js
│   │               jquery.js
│   │               language_data.js
│   │               minus.png
│   │               plus.png
│   │               pygments.css
│   │               searchtools.js
│   │               underscore-1.3.1.js
│   │               underscore.js
│   │
│   └───source
│       │   conf.py
│       │   index.rst
│       │   modules.rst
│       │   src.rst
│       │
│       ├───_static
│       └───_templates
└───src
        nopes.py
        sqrer.py
        __init__.py

这是我的conf.py：

# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.

import os
import sys
import pathlib

path = pathlib.Path(__file__).resolve() / '..' / '..' / '..' / 'src'

# sys.path.insert(0, os.path.abspath('..\src'))
sys.path.insert(0, os.path.abspath(path))


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

project = 'TEST PROJECT'
copyright = '2020, Cerberton'
author = 'Cerberton'


# -- 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']


# -- Extension configuration -------------------------------------------------

标签： pythonpython-sphinx