问题标签 [sphinx-napoleon]
For questions regarding programming in ECMAScript (JavaScript/JS) and its various dialects/implementations (excluding ActionScript). Note JavaScript is NOT the same as Java! Please include all relevant tags on your question; e.g., [node.js], [jquery], [json], [reactjs], [angular], [ember.js], [vue.js], [typescript], [svelte], etc.
python - sphinx autodoc-skip-member 处理程序:使用拿破仑时无法显示 __init__()
我想__init__()
在我的 sphinx 生成的文档中包含文档字符串。
我正在按照这个 stackoverflow 问题的公认答案添加处理程序,autodoc-skip-member
但仍然无法看到我的__init__()
文档。块内的跟踪代码if name == "__init__":
显示我正在点击该代码。
凭直觉,我'sphinx.ext.napoleon'
从我的extensions
定义中删除,离开
然后我可以看到__init__()
文档。
我在拿破仑文档中看到的唯一似乎相关的是napoleon_include_special_with_doc
,它说默认为True
. 将其显式设置为True
inconf.py
似乎并没有改变任何东西。
ETA:如果我添加以下方法:
我__blah__()
在我生成的文档中看到。
- 如果我将名称更改
__blah__
为__repr__
或__str__
,我会在生成的文档中看到它们。 - 如果我注释掉现有的
__init__
并更改__blah__
为__init__
我看不到它。
所以它似乎特定于__init__()
.
这是一个已知问题吗?在使用拿破仑时是否有另一种方法来控制它?
python - 'autodoc_default_flags' 如何在 python Sphinx 配置中工作?
我正在尝试使用 Sphinx 1.4 和扩展为我的 python 类生成sphinx-apidoc
文档sphinx.ext.autodoc
。
我有很多模块,我希望每个模块只显示类名,而不是类中方法的完整列表(在我的代码中都有文档字符串)。
这是我的conf.py
文件的片段:
这是一个玩具模块 ( my_module.py
),我用它来了解 Sphinx 的工作原理:
我只显示这个类的代码,以防我需要在我丢失的文档字符串中做一些事情。
我运行 sphinx-apidoc 来生成 rst 文件:
sphinx-apidoc -f -M -e -o docs/ /blah/sphinx/src/
然后构建:
制作html
我可能不清楚autodoc_default_flags
应该做什么。我认为当您在设置了这些标志的情况下运行 sphinx-apidoc 时,这些标志将应用于 .rst 文件中的指令。但是,在我运行 sphinx-apidoc 之后,我得到了这个 .rst 文件:
由于设置了这些标志,我没想到:members:
会被应用,但它确实存在!并且 html 页面具有完整的方法及其文档字符串。
FWIW,autodoc_member_order
正在工作;我可以设置它来切换方法出现的顺序。
所以我的问题:
- 应该做我
autodoc_default_flags
所描述的还是我误解了它? - 如果它可以用来自动隐藏构建中的成员,我是否正确使用它?如果是这样,关于为什么我仍然被
:members:
添加到 .rst 文件中的任何想法? - 如果我误解了它,那么它到底有什么作用?以及如何自动从我的构建中隐藏方法文档字符串?
理想情况下,我想要像 SciPy 这样的东西,例如这里:
http://docs.scipy.org/doc/scipy/reference/cluster.hierarchy.html
为此,我正在玩拿破仑和 sphinx.ext.autosummary 扩展,但似乎只有 apidoc 应该能够隐藏类方法文档。
python - sphinxcontrib.napoleon 和 numpy.numpydoc 之间的区别
我正在使用Numpy 样式的 docstrings为 Python 项目编写文档。
numpydoc和napoleon是两个 Sphinx 扩展,它们解析 Numpy 样式的文档字符串以生成文档。第一个用于 Numpy 项目本身,第二个与 Sphinx 一起提供。
使用一个扩展而不是另一个的优点和缺点是什么?
python - Sphinx 1.4+ 和带有 sphinx-napoleon 的 Returns 中的块文字不再起作用
我正在为遵循本指南的 python 项目编写文档:
http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
确切地说,指南的这一部分:
该Returns
部分支持任何 reStructuredText 格式,包括文字块::
我的代码如下所示:
对于 sphinx 1.3.5-1.3.6,它按预期工作。
对于 sphinx 1.4.0-1.4.1 它会抛出这样的错误:
python-sphinx - 使用 Sphinx napoleon 创建指向其他版本标准库的类型链接
我使用 Sphinx 和 Napoleon 以及 autodoc 扩展来记录一个 Python 项目,以解析 Google 样式的文档字符串。由于 Google 风格涉及指定参数的类型,Sphinx 会自动创建指向标准库中标准类型文档的链接。Intersphinx 但是,默认情况下它链接到文档的 2.7 版本,而我想链接到 3.x 版本。我该如何控制这种行为?
python - 禁用属性名称的 ivar 自动交叉引用的某种方法
当使用带有 google docstrings 的 Napoleon(我没有测试过 numpy,但我怀疑有类似的问题)并将napoleon_use_ivar
选项设置为 时True
,它会创建指向实例变量名称的链接。这些名称显然很常见(例如“名称”),并且将它们链接到一些随机定义没有帮助 - 有什么方法可以禁用它吗?
给定以下文档字符串:
它将尝试name
在 html 输出中进行交叉引用。考虑到目标的模糊性,它抱怨这一点:
但是,它仍然会在 HTML 输出中创建一个链接——如果您单击该name
属性,它会愉快地将您发送到一些与当前属性无关的随机符号。有没有办法禁用这种行为?
如果napoleon_use_ivar
设置为False
这不会发生,但属性输出一点也不紧凑,而且很难阅读。
这不是拿破仑特有的 - 如果您手动指定属性,ivar
它还会以您无法控制的方式交叉引用它们:
那仍然有一个链接name
。
python - 使用 NumPyDoc 样式的具有 Napoleon Sphinx 扩展的类方法列表
我正在使用 NumPyDoc 样式的文档字符串来记录 Python 包。我想从'numpydoc' Sphinx 扩展切换到Napoleon,因为我发现它以更紧凑和可读的方式格式化文档字符串。但是,它并没有在文档顶部列出类的方法,这是我发现 numpydoc 的一个非常有价值的特性。有谁知道如何在拿破仑中手动打开它?
django - 为 Django 项目生成文档时,Sphinx 失败
我正在尝试使用带有autodoc和拿破仑扩展的Sphinx为我的 Django 项目自动生成文档。
使用sphinx-quickstart
我创建了以下结构:
我已经定制docs/source/conf.py
以反映我的项目结构。
然后我转到项目的根目录并运行sphinx-apidoc -f -o docs/source .
. 这会将.rst
每个模块的文件添加到docs/source
.
最后我去MyDjangoProject
跑步make html
。这失败,每个模块都有一个错误说
我究竟做错了什么?
python-sphinx - Google 样式的文档字符串示例部分未呈现为代码片段
我最近开始向我的项目添加文档,并且正在尝试遵循 Google 样式指南。我正在使用 Sphinx 生成文档,并使用 Sphinx 扩展名拿破仑来弥合 Google 样式指南和 reST 之间的差距。
我在渲染参数和注释时没有问题,但我似乎无法让示例部分呈现代码片段。
我还尝试了示例部分的双冒号。