问题标签 [sphinx-apidoc]

我正在尝试使用 Sphinx 为我的代码库自动生成基本文档。但是，我很难指示 Sphinx 递归扫描我的文件。

我有一个 Python 代码库，其文件夹结构如下：

我在 中运行 sphinx-quickstart <workspace>，所以现在我的结构如下所示：

我已经阅读了快速入门教程，尽管我仍在尝试理解文档，但它的措辞让我担心 Sphinx 假设我将为我的代码库中的每个模块/类/函数手动创建文档文件.

但是，我确实注意到了“automodule”语句，并且在快速启动期间启用了 autodoc，所以我希望大部分文档都可以自动生成。我修改了我的 conf.py 以将我的 src 文件夹添加到 sys.path，然后修改我的 index.rst 以使用自动模块。所以现在我的 index.rst 看起来像：

我在子包中定义了几十个类和函数。然而，当我运行时：

它报告：

这似乎无法在我的包中导入任何内容。查看生成的 index.html 在“Contents:”旁边没有显示任何内容。索引页面只显示“mypackage (module)”，但点击它显示它也没有任何内容。

如何指导 Sphinx 递归解析包并为它遇到的每个类/方法/函数自动生成文档，而不必自己手动列出每个类？

我有一个包含多个大型应用程序的项目，其中设置和应用程序文件被拆分。

目录结构是这样的：

项目名

• _初始化_.py
• 应用
• _初始化_.py
• 应用程序1
• 应用程序2
• 第三方
• _初始化_.py
• 库1
• 库2
• 设置
• _初始化_.py
• 安装的应用程序.py
• 路径.py
• 模板.py
• 语言环境.py
• ...
• 网址.py

每个应用程序都是这样

• _初始化_.py
• 行政
• _初始化_.py
• 文件1.py
• 文件2.py
• 楷模
• _初始化_.py
• 模型1.py
• 模型2.py
• 测试
• _初始化_.py
• 测试1.py
• 测试2.py
• 意见
• _初始化_.py
• 视图1.py
• 视图2.py
• 网址.py

如何使用 Sphinx 自动生成文档？

我想要在设置模块或 INSTALLED_APPS（不是以 django.* 或 3rdparty.* 开头）中的每个类似的东西给我一个基于 docstring 的自动文档输出。

并在 git commit 之前自动生成文档并运行测试

顺便提一句。我试着用手工制作 .rst 文件

但是对于这么大的项目来说很糟糕，而且它不适用于设置

有没有自动生成方法之类的？

我没有绑定到 Sphinx，是否有更好的解决方案来解决我的问题？

过去有几个关于这个主题的线程声称 Sphinx 根本不支持这个。我有我的疑虑，但要么它已经更新，要么它的文档被很好地隐藏了，因为这是网站上的一个链接，另有说明： http ://www.sphinx-doc.org/en/master/usage/重组文本/domains.html#cpp-domain

无论如何，我是 Sphinx 的新手，但我正在尝试使用它（最终）使用来自某些源 C++ 代码的一些文本来自动化文档。sphinx-apidoc -o ...到目前为止，使用该命令时我无法到达任何地方。创建了一个几乎空白的文档。我可能没有使用正确的指令，因为我不知道如何 - 支持文档无法帮助我。

任何人都可以就使其工作所需的基本步骤提供一些帮助吗？如果无法从 C++ 自动生成文档，C++ 域的用途是什么以及如何使用它们？

所以我在两个不同的目录中有我的 python 源文件：-

例如

如何使用sphinx-apidoc递归方式查看两个目录以生成我的 reST 文件？

明显地，

工作得很好但是当我尝试运行时

再一次，sphinx 告诉我“docs/source/modules.rst 已经存在，正在跳过”这当然是真的，因为我已经运行sphinx-apidoc过一次来生成它。

那么如何执行一次并在两个目录中搜索呢？

我正在通过以下方式为 django 项目构建我的 sphinx 文档：

现在它包括了我不想在我的文档中包含的所有南方迁移。我现在尝试通过以下方式排除它们：

现在它们不再被记录，但仍列在模块下。我怎样才能排除它们？

我正在尝试为测试 Python 项目创建文档，然后再为实际项目创建文档。我的系统：Win7 64 位，python 2.7.5 64 位。

我的项目名称是testDoc。它包括名为t的 python 包，其中包括 2 个模块t1和t2和__init__.py.

__init__.py包含：

t1.py 包含：

要创建文档，我在testDoc的命令行中运行：

Sphinx 创建了许多文件，根据 Sphinx 文档可以。然后，修改conf.py

我进入docs文件夹并输入

并得到以下错误输出：

怎么了？谢谢。

我通过 sphinx-apidoc 生成文档。文档被生成到默认的 rst 模板。如何使用自己的 rst 模板生成文档？

我正在开发一个只有一个 .py 模块的 Python 库，并且我正在尝试从文档字符串中为其生成文档。我已经设置了 Sphinx 并运行了 spinx-quickstart 脚本，但是当我尝试运行时（在 docs 目录中）

但它只是说：

是否有其他一些 Sphinx 脚本可以自动生成单个文件？我想过只是运行它，..但后来我想它会运行到我的测试目录并尝试从我的单元测试中生成文档......

我想知道注释格式是什么，以便使用 Sphinx 的 sphinx-apidoc 实用程序进行自记录代码。我可以让这个实用程序为每个 python 文件生成一组 reStructuredText 文件，但是这些文件仍然需要填写。我正在寻找一种方法来获取这个实用程序，或者其他一些 Sphinx 实用程序来生成文档python 编码文档字符串。我知道这需要熟悉传统的评论格式，我希望能被指出这个参考材料。谢谢！

我有一个带有函数（lib.py）的python文件，没有类。每个函数都有以下样式：

我只想用 Sphinx 记录每个函数（输入和输出）。

完成sphinx-quickstart之后，我用我的 lib.py在conf.py中定义了路径。但是输出的 HTML 文件（欢迎页面）是空的。

如果我在index.rst中写自己：

没关系，它在 html 文件中显示输入和输出。但是如何自动完成呢？

通常，我认为，在执行sphinx-apidoc -o之后必须在lib.rst中执行此操作，但在lib.rst中只有：

有人可以逐步解释我必须做什么吗？