.rst我的Sphinx树中有很多文件被故意排除在任何索引树之外.我收到警告
/filename.rst:: WARNING: document isn't included in any toctree
如何在Sphinx中抑制特定警告？
我们有一个用(优秀的)Sphinx记录的多模块项目.我们的设置与邮件列表中描述的设置没有什么不同.总的来说这很棒!但是我们有一些关于这样做的问题:
子模块目录将包括索引链接.充其量这些将链接到错误的指数.(在最坏的情况下,这似乎会引发Sphinx中的错误,但我正在使用devel版本,这是合理的).有没有办法只为最顶层的toctree生成索引链接？
是否有保持Sphinx配置在多个项目之间同步的最佳实践？我可以想象在一起乱砍某些东西from common_config import *,但对其他方法感到好奇.
虽然我们在这里,但邮件列表中提出的问题(替代symlinking子项目文档？)从未得到回答.这对我来说并不重要,但对其他读者来说可能很重要.
我正在使用Sphinx为我的项目生成文档.
在这个项目中,我描述了yaml文件中的可用命令列表,一旦加载,就会在表单中生成一个字典,{command-name : command-description}例如:
commands = {"copy" : "Copy the highlighted text in the clipboard",
"paste" : "Paste the clipboard text to cursor location",
...}
我想知道的是,如果sphinx中有一个方法在make html循环期间加载yaml文件,以某些reStructuredText格式(例如定义列表)翻译python字典并包含在我的html输出中.
我希望我的.rst文件看起来像:
Available commands
==================
The commands available in bla-bla-bla...
.. magic-directive-that-execute-python-code::
:maybe python code or name of python file here:
并在内部转换为:
Available commands
==================
The commands available in bla-bla-bla...
copy
Copy the highlighted text in the clipboard
paste …假设我有一个Sphinx项目,其中包含以下来源:
index.rst
installation.rst
templating/
index.rst
module.rst
fieldtype.rst
index.rst(主页)有以下TOC树:
.. toctree::
:titlesonly:
installation
templating/index
我希望我的模板包含一个侧栏,列出所有3个顶级页面(主页,安装,模板/索引).
我已经尝试在主页中添加第二个隐藏的TOC树:
.. toctree::
:hidden:
index
.. toctree::
:titlesonly:
installation
templating/index
这实际上给了我想要的结果,除了它使next变量设置为当前页面.所以这个代码在我的模板中:
Next up: <a href="{{ next.link }}">{{ next.title }}</a>
...始终从主页输出主页链接.不好.
我一直试图将实际的主页链接硬编码到模板的侧边栏中:
{% set homeClass = 'current' if pagename == 'index' else '' %}
<ul class="{{ homeClass }}">
<li class="toctree-l1 {{ homeClass }}"><a class="{{ homeClass }} reference internal" href="/index.html">Home</a></li>
</ul>
{{ toctree() }}
这也有效,除了我不想强迫在Web服务器的webroot上访问文档 - 我希望它们也可以在文件系统中工作.
我不能简单地将URL设置为"index.html",因为当你在templating /中的文件中时,这将不起作用.
我错过了一些明显的东西吗 必须有一种方法可以将主页放入TOC,而不会破坏next链接和在本地文件系统上工作的动态路径,即使是在子文件夹中也是如此.
似乎有太多的Python文档工具.我碰到的另一个是epydoc.似乎Sphinx是事实上的标准,因为它用于生成官方Python文档.有人可以帮我理清Python文档工具的当前状态吗？
如果我有一些文档,例如Galleria的文档,我该如何设置它以便在运行make html命令时它会在每个页面上添加一个自定义页脚？
我看到如果我将它输出为pdf格式,我可能会使用conf.py 的latex前言部分.
谢谢!
使用Sphinx生成文档时,我希望能够生成两个版本的文档:一个包含所有内容,另一个只包含一组特定页面.实现这一目标的最佳方法是什么？
我可以编写一个构建脚本来移动文件来实现这一点,但如果有一种方法可以告诉sphinx在特定构建期间排除或包含特定文档,那将会非常好.
过去在这个主题上有几个主题,声称Sphinx根本不支持这个.我有疑虑,但要么它已经更新,或者它的文档被很好地隐藏了,因为这里有一个链接在网站上另外说明: http://sphinx.pocoo.org/latest/domains.html#array:牛逼:::标-operatorC
无论如何,我是Sphinx的新手,但我正在尝试使用它(最终)使用来自某些源C++代码的一些文本来自动化文档.到目前为止,当使用sphinx-apidoc -o .......命令时,我无法到达任何地方.创建了几乎空白的文档.我可能没有使用正确的指令,因为我不知道如何 - 支持文档无法帮助我.
任何人都可以提供一些帮助来完成它的工作所需的基本步骤吗？如果无法从C++自动生成文档,那么C++域是什么以及如何使用它们？
我想使用ReStructuredText在标题和图像之间添加一个空白行(或添加更多空格):
====
John
====
.. image:: _static/john.JPG
:alt: John
:height: 300px
:width: 400px
但我不知道该怎么做？
有时Python中的函数可能接受灵活类型的参数.或者它可以返回灵活类型的值.现在我不记得现在这样一个功能的一个很好的例子,因此我在下面用玩具示例展示这样的功能可能是什么样子.
我想知道如何使用Sphinx文档表示法为这些函数编写文档字符串.在下面的示例中,参数可以是str或int.同样,它可能会返回str或int.
我给出了一个示例文档字符串(两者都是默认的Sphinx表示法以及Sphinx拿破仑扩展所理解的Google表示法).我不知道这是否是记录灵活类型的正确方法.
Sphinx默认表示法:
def add(a, b):
"""Add numbers or concatenate strings.
:param int/str a: String or integer to be added
:param int/str b: String or integer to be added
:return: Result
:rtype: int/str
"""
pass
狮身人面像拿破仑谷歌记号:
def add2(a, b):
"""Add numbers or concatenate strings.
Args:
a (int/str): String or integer to be added
b (int/str): String or integer to be added
Returns:
int/str: Result
"""
pass
在文档字符串中表达多个类型的参数或返回值的正确方法是什么？