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

问题描述

我看了许多教程和视频，并通过使用Sphinx 生成文档的过程来学习其中的一个，在这一点上，我深信我的项目结构有问题。我正在运行Windows 10 Pro，2004; Python 3.7.9;狮身人面像3.3.0。

我创建了一个全新的项目sphinx_test，请按照以下步骤测试我的狮身人面像技能：

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

解决方法

暂无找到可以解决该程序问题的有效方法，小编努力寻找整理中！

如果你已经找到好的解决方法，欢迎将解决方案带上本链接一起发送给小编。

小编邮箱:dio#foxmail.com (将#修改为@）

python python-sphinx