Python 如何正确设置Sphinx的项目目录

我看了很多教程和视频，其中一个介绍了使用Sphinx生成文档的过程，现在我确信我的项目结构有问题。我正在运行Windows10Pro，2004；Python 3.7.9；斯芬克斯3.3.0

我创建了一个全新的项目

sphinx_test

，通过以下步骤测试我的sphinx技能：

创建一个新的virtualenv

python-m virtualenv sphinxtest

激活它

sphinxtest\Scripts\Activate

安装Sphinx和要求

pip安装Sphinx

创建一个新的项目文件夹

mkdir sphinx_test

并导航到它

cd sphinx_test

为源代码和所有子模块创建子目录

mkdir src

用随机docstring（

nopes.py

和

sqrer.py

）创建一些愚蠢的示例

*.py

文件

创建文档目录

mkdir docs

并导航到其中

cd docs

执行

sphinx快速启动--ext autodoc

，选择单独的

build

和

source

目录

修改

conf.py

，将

/src/

添加到

路径

修改

索引.rst

，在

目录树下添加
模块
：

从

docs

目录中运行

sphinx apidoc-o.\source\..\src\

运行

makehtml

并获取以下内容：

这是目前的文件夹结构：

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 -------------------------------------------------

请尝试

sys.path.insert（0，os.path.abspath（'../../src'））

。

src

的路径必须相对于

conf.py

。我也不知道你声明的

path

变量是什么，但是看起来。。。UH创造性的

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