Windows 中的 Sphinx 不会为模块创建文档答案

【问题标题】：Sphinx in Windows doesn't create docs for modulesWindows 中的 Sphinx 不会为模块创建文档
【发布时间】：2019-11-09 20:11:26
【问题描述】：

我正在尝试使用 sphinx 为我的项目创建文档。我的项目结构是这样的。

Project_root
|-docs
  |-_build
  |-_static
  |-_template
  |-rst
  |-conf.py
  |-Makefile
  |-make.bat
  |-index.rst
|-modules
  |-__init__.py
  |-module1.py
  |-module2.py

我通过在我的文档目录中运行sphinx-quickstart 来设置此目录，并且模块目录包含我需要创建文档的程序模型。文件包含文档字符串以创建这样的自动文档。

"""Class represent a sentence of a comment of a bug report

Parameters
----------
sentence_id : str
    sentence_id is a combination of turn_id and the sequence number
    (ex: 1.3 means turn 1 and 3rd sentence of the turn)
text : str
    orginal sentence text as appeared in the bug report
cleaned_text : str
    cleaned text after removing irrelevant characters, stop words,
    turning to lower case and lemmatizing
tags :list of str
    tags indicate the type of the sentence (description, clarification,
    plan, resolution) and/or picked by certain algorithm
"""

我已将conf.py中的路径更改如下。

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

当我运行sphinx-apidoc -o rst ..\models 时，它只会创建models.rst 和modules.rst。没有为 module1.py 和 module2.py 创建 rst。

我想知道我的配置发生了什么。

编辑：我忘记在我的目录树中添加 `init.py。

【问题讨论】：

modules 不是 Python 包，因为它缺少 __init__.py 文件，并且 Sphinx 只能导入 Python 包，所以添加一个空的 __init__.py。也可以试试 abspath('../') 因为 Python 不关心 Windows 目录的反斜杠。
@Steve Piercy：感谢您在abspath 中指出我的错误。这实际上解决了我的问题。请注意将此作为您的答案，以便我接受。但是，我注意到在教程中运行sphinx-apidoc 时，它会为每个模块创建 .rst 文件。我不明白那些。但是文档在那里。任何想法这里发生了什么。
请创建一个新问题，而不是在评论中添加一个新问题。包括full command with appropriate options。

标签： python-3.x windows python-sphinx

【解决方案1】：

尝试abspath('../')，因为 Python 不关心 Windows 目录的反斜杠。

【讨论】：