问题标签 [sphinx-apidoc]

我为我的 click 应用程序使用 sphinx-click 扩展名，我想使用 sphinx-apidoc仅为子模块生成 .rst 文件。

我已经使用 pythons Sphinx 文档库大约一年了，我有一个用例……我不太清楚……也许我现在只是瞎了眼。

无论如何，我有一个 cli 工具，其结构类似于

其中 cli_entry 是一个点击应用程序，它导入my_tool.utils.foo和my_tools.utils.bar 因为这是使用 Click 库。我决定使用sphinx_click扩展来记录其中的任何命令cli_entry.py（它记录了所有的命令）。

但这是问题所在，我想用它来为模块sphinx-apidoc中的所有内容生成 .rst 文件。./my_tool/utils/当我使用该命令作为sphinx-apidoc -o ../docs/utils my_tool/utils我得到的输出文件时

一开始看起来不错，但打开utils.rst文件后看起来像

然后，当我使用（来自 sphinx 生成的 makefile）构建文档时，make html我收到一条错误消息，说Failed to import 'utils.foo': no module named utils.foo那是因为导入应该以my_tool.utils.foo

如何使用sphinx-apidoc仅生成子模块并包含正确的导入路径？也许这是我在conf.py.. 中缺少的东西。也许这是我从 sphinx-apidoc 中缺少的一个选项？

编辑：我应该提到我可以使用exclude_pattern参数......但我宁愿不必在我的根目录中指定每个 cli 文件。前任。在我有的情况下cli_entry.py，cli_commandgroup1.py...... cli_commandgroupN.py我希望这个解决方案足够动态，只支持子模块。

编辑：我尝试使用sphinx-apidoc -o ../docs/utils my_tool/，这会创建以下输出

现在在my_tool.utils.rst文件中，导入是正确的，并且可以生成文档。

指定的问题my_tool/是my_tool.cli_entry.rst，当这个 .rst 文件已经使用 click-sphinx 扩展名创建时，它会被创建。

我正在使用 sphinx 使用我的 python 模块中的 docstring 自动生成 html。为此，我使用了名为“sphinxdoc/sphinx”的 sphinx 的 docker 镜像。我通过将我的 python 项目（在 DocString_Project 目录中）映射为一个卷来运行 sphinx。步骤如下。

1. 快速开始： docker run -it --rm -v /path/to/project/DocString_Project:/docs sphinxdoc/sphinx sphinx-quickstart

2. 将 conf.py 文件编辑为：

3. 生成 .rst 文件。

4. 这会生成 .rst 文件，如下所示。

5. 在 index.rst toctree::下面添加模块

6. 制作html

问题生成的 HTML 文档正确显示了最外层模块的文档字符串；docstring.py和sphinxtutorial.py但不显示nested1和nested2内任何嵌套模块的文档。但是，sphinx apidoc 确实检测到它们的存在。

如何显示来自nested1 和nested2 下模块的文档？

注意：嵌套的 py 模块与父目录中的对应模块完全相同，即 docstring.py 与 docstringnested1.py 和 docstringnested2.py 相同

更新：.rst 文件的内容： allmodules.rst

allmodules.nested1.rst

allmodules.nested1.nested2.rst

制作 html 错误/警告

我正在尝试在像“com.company”这样的命名空间中使用像“project-a”这样的包，并带有隐式命名空间。

我发现 sphinx-apidoc 没有将我的包放入文档中的 toc 中，我怀疑是因为 thecom和company命名空间中都没有任何内容。

sphinx-apidoc 与 pyscaffold--implicit-namespaces的标准配置一起运行，为我提供了一个基本项目。

我在 sphinx-build 输出中得到以下信息：

在我开始研究狮身人面像代码之前有什么想法吗？

我已经在这里发布了代码 - 目前真的没什么：https ://github.com/nward/com_company_project-a

我有一个示例项目：

当我使用sphinx-apidoc它时，它会生成非常难看的标题，如下所示：src.some_package.some_subpackge.some_module. 我想要做的是不要在生成的 ToC 中重复前面的标题。生成这样的东西：

像这样的东西是我的偏好：

我曾尝试使用此处描述的方式生成 api-doc，但我没有运气。

目前我使用生成狮身人面像项目：sphinx-quickstart然后将其附加到makefile：

并插入一个api.rstindocs/文件夹。该文件的内容是：

我正在开发一个 Python 包，它允许用户像这样导入它的函数：

我正在用 sphinx 记录代码。我先跑了sphinx-quickstart，然后我改成conf.pyinclude sys.path.insert(0, os.path.abspath(‘../../src/mymodule’))。然后我跑sphinx-apidoc -f -o source ../src/mymodule了make html。目录结构是这样的：

输出列出了“mymodule.modulecode”子模块。但由于 my __init__py，用户没有明确导入modulecode.

是否有一种自动化的方式使 sphinx 文档列出函数mymodule.afunction()（由用户访问），而不是mymodule.modulecode.afunction()（用户不调用）？

我为 Python 3 构建了一个语言扩展，它允许它的用户生成带有“.pytsl”后缀的 Python 文件。我想使用 Sphinx 来记录这些文件。但是，当在特定目录上运行 sphinx-apidoc 时，该目录下的“.py”文件会被转换为“.rst”，而“.pytsl”文件不会。

我在文档和帮助部分中搜索了 sphinx-apidoc，但找不到允许我启用 sphinx-apidoc 来识别扩展名为“.py”以外的文件的方法。

有没有办法做到这一点？如果没有，可以支持吗？

我在一个测试项目中使用 Sphinx 4.4.0 。我使用sphinx.ext.autodoc和sphinx-apidoc。

但并非所有 py 文件都被识别。它看起来像以文件名开头_的文件被忽略（例如_mypackage.py）。但我不确定那个角色是原因还是其他原因。

您是否知道修改该行为的选项？

这是项目结构