问题标签 [python-sphinx]

我目前使用Sphinx生成 LaTeX 输出，使用 pdftex 将其转换为 PDF 以进行书本式输出。

目前，我在一个有界框内显示了通知、警告和其他“警告”，其样式看起来有点像这样：

生成这样一个框的 LaTeX 如下所示：

LaTeX .sty 文件中有一系列命令提供框行为：

我不想只在通知周围有一个框并在框内有一个表示通知类型的词，我想保留警告周围的框，但用图像替换框中的“警告”一词，就像这样：

我无法更改 Sphinx 呈现的 \begin{notice} ... \end{notice} 乳胶文字（嗯，我可以，但它真的很痛苦）。我宁愿把逻辑放在一个新的 \newenvironment{notice} 宏中。谁能推荐一个策略？到目前为止，我所做的一切都以眼泪告终。

如果此代码是我的文档中的块引用，我需要做什么才能让Sphinx在生成文档时运行它？我尝试添加

到其中一个.rst来源和 Sphinx doctest 扩展conf.py，但我收到一个错误，抱怨函数体第一行出现意外缩进。Sphinx 的 doctest 是否能够运行文档中定义的功能？

我使用sphinx-quickstart创建了一个 Sphinx 文档。

1. 有没有关于自定义外观的好例子/教程？专门修改表头，加个logo。

2. 是否有一些带有可下载 Sphinx 文档的项目？我想看看他们是如何定制自己的外观的。

更新：默认设置支持添加徽标，只是没有特别好的文档记录。查看conf.py设置*_logo。

是Sphinx，有没有办法自动将文本链接#112到Tracr1023中的相应票证/变更集？

例如：

有关更多示例，请参阅TracLinks。

与此章的帖子类似，我看到 Sphinx 生成不可读的 graphviz 输出：

如何生成可读输出？

• 如果我添加什么都不会发生-Gfontsize=140
• 如果我告诉它使用neato而不是dot它会产生可读的输出，但图形不是树状的。

所以我已经有点习惯了 Javadoc 风格的文档。通过查看 Python 代码的各种示例，我发现，乍一看，文档似乎缺少很多信息。

好处：您很少看到不言自明的文档。文档字符串通常是一段或更少的英文标记，它们集成在一起，而不是在单独的行中突出。

坏处：结合 Python 的鸭子类型，我发现许多函数不清楚它们所期望的参数。没有类型提示（duck-hinting？），并且通常最好知道参数应该是类似列表的、类似字符串的、类似流的。

当然，Javadoc 是为较低级别的语言设计的，没有 Python 的强大自省能力，这可能解释了不那么冗长的文档理念。

关于 Python 文档标准和最佳实践的任何建议？

我更喜欢在声明参数的同一行记录每个参数（根据需要），以便应用DRY

如果我有这样的代码：

如何避免重复文档字符串中的参数并保留参数说明？

我想避免：

这在带有某种装饰器操作的 python 2.6 或 python 3 中是否可行？还有其他方法吗？

我正在用Sphinx编写一些文档，我想只为 HTML 文档打印出某个文本块，而不是为 LaTeX 文档打印。有些东西告诉我我应该能够做到这一点，sphinx.ext.ifconfig但我不知道怎么做。有谁知道如何做到这一点？

当我构建从 sphinx 生成的 LaTeX 文件时，TOC 条目和节标题是蓝色的。有没有一种简单的方法可以禁用这些项目的着色？如果没有，有没有一种简单的方法可以让它们变黑？我的目标是在非彩色打印机上打印文档，并且当我这样做时，目录和标题看起来不像文本的其余部分那么暗。

如果可能的话，我想进行一项适用于整个文档的更改。

注意：我正在使用 howto 文档类。

更新

感谢 ddbeck 的输入，我仔细查看了sphinx.sty哪些定义了我需要更改的颜色。我设置（创建）latex_elements字典conf.py如下：

这完全符合我的要求。谢谢ddbeck！

我使用Sphinx Python 文档生成器。创建 PDF 文档非常容易和简单，但我有一个问题。

所有生成的 PDF 文档都有英文单词，如“chapter”、“release”和“part”。

如何用另一种语言覆盖这些英文标签，或完全删除它们？