问题标签 [sphinx-apidoc]

我正在尝试使用 Sphinx 来记录我一直在研究的 Python 库。在此过程中，我一直在使用这篇文章作为粗略指南。但是，我在让 Sphinx 正常工作时遇到了问题。

一旦一切都设置好了，Sphinx 就已经安装好了，我已经在我从项目根目录输入的代码中添加了文档：

输出：

接下来，我分别编辑 docs/conf.py 以确保我的 sys.path.insert(0, os.path.abspath('/Users//path/to/mypackage')) 是正确的。

但是，当我尝试通过以下方式构建文档（从 docs 目录中）时：

我受到了欢迎：

我已经使用 sphinx-apidoc 并与其他库一起制作 html 并且从未遇到过这个问题，所以我有点不知所措。有什么想法吗？

目前，每当我运行sphinx-build时，只有在源文件发生更改时才会选择并使用内联文档字符串。我试过sphinx-build用-a开关打电话，但这似乎没有效果。

如何强制完全重建 HTML 输出并强制执行 autodoc？

I understand that the following generates rst for all modules, excluding the index.rst

And the following generates everything, including index.rst, conf.py, Makefile, etc

The problem is that sphinx-apidoc does not generate a correct conf.py, so I have to always manually modify conf.py to include the correct sys.paths. If I modify my python code in "very_good" folder, I should run the sphinx-apidoc command without "-F", so conf.py is preserved. However, if I add a new module under very_good directly, index.rst is not updated without the "-F" option, which means my new module will not be in the doc. I guess the solution is to either someone generates the index.rst file only, or using "-F" option without overriding the conf.py. Is there a way to do it?

我想使用 Sphinx 来记录一个目前没有很好记录的大型项目。特别是，我想sphinx-apidoc在记录代码时使用它来生成文档。

但是，我也想要一些关于如何使用项目等的教程页面，但是当我调用sphinx-apidoc它时似乎会立即生成整个文档。

所以我的问题是：这里正确的工作流程是什么，这样我就可以编写要手动编写的教程页面，同时更新代码中的文档？请注意，如果我更新手动编写的教程页面（例如包含在 中index.txt）并运行，sphinx-apidoc我将丢失它们，因为整个文档是立即生成的。

一般来说，有没有关于如何继续构建文档的指导方针？

注意：不便之处在于基本过程假定您已经准备好所有代码文档，并且在您继续生成文档时不会进行任何更新。至少这是我需要解决的。

我正在尝试用 Python 记录一个包。目前我有以下目录结构：

这棵树是发射的结果sphinx-quickstart。在conf.py我未注释的情况下sys.path.insert(0, os.path.abspath('.'))，我有extensions = ['sphinx.ext.autodoc'].

我index.rst的是：

在所有的文件中__init__.py，我都有一个文档字符串，模块foo.py和bar.py. 但是，在make html项目中运行时，我看不到任何文档。

问题背景：

我想在我的 django 项目中使用 sphinx 编写文档，并使用我的 django 代码注释自动创建文档。

现在我有一个 django(1.9) 项目，文件结构如下：

然后，如您所见，我在docs其中放置了一个包含Sphinx文档项目的文件夹。

现在我可以编辑*.rst文件和build html.

但是当我尝试autodoc内容时，它失败了。

以下是我所做的：

首先，我将这些添加到docs/conf.py，参考：https ://stackoverflow.com/a/12969839/2544762 ：

然后，我做了一个sphinx-apidoc动作：

之后，在 中docs/documentations，我得到了一些.rst文件：

之后，我运行make html，并警告：

我做错了什么？如何使用 django 代码构建文档？

假设我们有一个如下所示的文档结构

现在我们使用以下命令生成文档：

./docs/这会在文件夹中生成几个文件，包括a ./docs/abc.rst，我现在可以make html在./docs/文件夹中使用 a 构建这些文件。

现在，在添加了一些附加功能后，./src/abc.py我想重建文档。我尝试了同样的事情，Sphinx 说其余文件已经存在，因此它没有得到更新。在更新文档之前，我必须手动删除相关文件。

现在的问题是，我如何在不删除.rst文件的情况下完成整个过程。

我有一个这样的项目结构：

__init__.py包含：

module.py包含：

使用sphinx-apidoc -o package/docs/ package/and sphinx-build package/docs/ package/docs/_build，文档Class看起来像这样：

类包.module。班级

     基础：对象

我想要这个输出：

类包。班级

     基础：对象

或者，更好的是，没有包名：

类 类

     基础：对象

用户不必知道类是在哪个文件中定义的；这些信息完全无关紧要，如果不是令人困惑的话。由于直接__init__.py导入Class包的命名空间，用户会将此类导入为from package import Class，而不是from package.module import Class，我希望文档反映这一点。

有没有办法让 sphinx 输出相对于包的命名空间的路径？

我正在使用 PyCharm 开发一个 Python 项目，现在我需要生成相应的 API 文档。我正在使用docstrings. 我读过关于 Sphinx 和 Doxygen 的文章，其中 Sphinx 是目前最推荐的。我试图配置 Sphinx whitin PyCharm，但我没有让它工作。

这是项目结构：

这是与Sphinx Quickstart命令的 I/O 交互

然后我移动到/docs文件夹

，编辑了conf.py文件：

并运行以下命令：

我以为我已经完成了，但这是我得到的糟糕结果，没有任何类和模块的文档。

索引.html

genindex.html

难道我做错了什么？在此先感谢您的时间。

我在 django 项目的生成文档中得到了一些遗漏的信息，例如first_name和last_name，email遗漏了（尽管它们是在父抽象类中定义的）。如何控制基于sphinx-apidoc扫描添加到文档中的内容？我的目标是根据文档自动生成文档，但似乎 sphinx-apidoc 应该只用于初始脚手架一次

我尝试使用:inherited-members:如下所示，但它仍然没有产生AbstractUser类中存在的 first_name、last_name、email

我执行以下命令

输出

我的应用程序/用户/models.py

我的狮身人面像 conf.py