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

Question

我看过大量教程和视频，了解使用 Sphinx 生成文档的过程，此时我确信我的项目结构存在问题。我运行的是 Windows 10 专业版，2004 年； Python 3.7.9；狮身人面像 3.3.0.

我创建了一个全新的项目

sphinx_test

来按照以下步骤测试我的Sphinx技能：

创建一个新的虚拟环境
```
python -m virtualenv sphinxtest
```
激活它
```
sphinxtest\Scripts\activate
```
安装Sphinx和要求
```
pip install sphinx
```
创建一个新的项目文件夹
```
mkdir sphinx_test
```
并导航到其中
```
cd sphinx_test
```
为源代码和所有子模块创建子目录
```
mkdir src
```
使用随机文档字符串（
```
*.py
```
和
```
nopes.py
```
）创建一些愚蠢的示例
```
sqrer.py
```
文件
创建文档目录
```
mkdir docs
```
并导航到其中
```
cd docs
```

执行

sphinx-quickstart --ext-autodoc

，选择单独的

build

和

source

修改
```
conf.py
```
，将
```
./src/
```
添加到
```
PATH
```
修改
```
index.rst
```
，在
```
modules
```
组下面添加
```
toctree
```
：

从
```
sphinx-apidoc -o .\source\ ..\src\
```
目录中运行
```
docs
```
。
运行
```
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 -------------------------------------------------

Answer 1

就其价值而言，此链接似乎非常清楚如何将所有文档连接到生成的

index.rst

文件。

https://www.sphinx-doc.org/en/master/usage/quickstart.html#setting-up-the-documentation-sources

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

问题描述投票：0回答：1

1个回答

最新问题

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

问题描述 投票：0回答：1

1个回答

最新问题

问题描述投票：0回答：1