标签: python-sphinx

我正在按照 numpy 文档字符串指南编写文档字符串。然后我使用 sphinx 的 autodoc 生成我的文档。在一些文档字符串中，我使用 LaTeX 公式（sphinx.ext.mathjax）。似乎这\r意味着一些特殊的事情，比如一条新线。如果我有以下命令：

"""
This :math:`\langle a, b\rangle` denotes the dot product of a and b
"""

它无法正确渲染。它将类似角度放入新行并给我一个错误：内联解释文本或短语引用起始字符串没有结束字符串 如果我用 \langle 替换 \rangle 一切正常。我怎样才能解决这个问题？

我对 sphinx 比较陌生，想为我的项目生成文档。我的函数之一的示例可以在 Predict.py 中找到：

def arima_rolling_forecast(training_set, testing_set, order, solver='lbfgs'):
    """
    Runs an ARIMA rolling forecast with a given training and testing set.
    :param pandas.Series training_set: training set.
    :param pandas.Series testing_set: testing set.
    :param collections.namedtuple order: ARIMA order (p, d, q).
    :param string solver: the solver used for the rolling average. Defaults to lbfgs.
    :return: the forecast of predicted values.
    :rtype: list
    """
    previous_results = list(training_set)
    predictions = []
    for result in testing_set:
        tmp_model = ARIMA(previous_results, order=order)
        tmp_model_fit = tmp_model.fit(disp=False, …

许多开源项目在文档页面的右上角使用“Fork me on Github”横幅。

仅举一个例子，让我们以 Python请求为例：

Github 博客上有一篇关于提供图像代码的横幅的文章：GitHub Ribbons

但没有解释如何在使用 Sphinx 生成的每个页面中添加链接，然后上传到 ReadTheDocs。

你能帮忙自动生成这个吗？我预计会有一个选项，conf.py但我没有找到。我的 Sphinx 配置是默认配置。

我有一个mod带有一些子模块的模块submod，并用于.. automodule:: mod.submod为其生成文档。

模块中元素（函数、类等）的签名现在显示限定名称，例如mod.submod.my_function(*args, **kwargs).

我希望 Sphinx 仅显示函数的名称，即签名my_function(*args, **kwargs)。

我有什么办法可以删除签名中的主要模块和子模块吗？

我是第一次使用“阅读文档” 。我正在为命令行系统编写文档，我的“代码示例”包括 shell 输出的日志。shell 输出最终看起来像这样

也就是说，服务（或者我对它的使用？）正在尝试将运行 shell 命令的示例格式化为源代码，并将 视为magento2:generate类常量。

我可以控制哪些代码块在阅读文档时获取源代码格式吗？我尝试在管理中不设置基本语言，但似乎没有效果。或者这是我需要在 sphinx 级别的 mkdocs 中控制的东西？（通过将 Markdown 或 sphinx 文件转换为漂亮的 HTML 文件来阅读文档）或者其他什么？还是我运气不好？

我有一个 readthedocs sphinx 文档，它使用 nbsphinx 显示 jupyter 笔记本。当我使用 autobuild 在本地构建文档时，我在 jupyter 笔记本的代码单元格中突出显示了语法。但在 readthedocs 上，代码单元没有任何语法突出显示。

我是否必须激活某些东西才能在这些单元格中突出显示语法？

我有一个类方法，其参数以下划线结尾，from_我用它autoclass来生成该类的文档。我希望参数from_在 Sphinx 文档中显示为普通文本，但目前它显示为超链接。

这是带有文档字符串的类方法的简化版本：

class Twilio:

    def get_messages(to=None, from_=None):
        """
        Get messages.

        `Args:`
            to: str
                Receiver.
            from_: str
                Sender.
        `Returns:`
            Messages: dict
        """
        return fetch_messages(to=to, from_=from_)

我正在使用以下方法生成此类的文档：

.. autoclass :: Twilio
   :inherited-members:

问题可以在本页最底部的函数中看到，get_messages您可以看到它被格式化为超链接。

我在向 Sphinx .html 文件添加自定义页脚时遇到一些问题。我正在使用sphinx_rtd_theme。我已经检查了这篇文章并尝试了它（以及评论中的一些建议）但无济于事。我不确定我错过了什么。如果我没有在这里发布足够的内容来实际指出导致问题的原因，我深表歉意。任何帮助或建议表示赞赏！

我的 css 主题文件已被我自己（很差地）修改过（我不是 HTML/CSS 人员！），但我认为这并不重要？我唯一能想到的另一件事是，当我重新编译输出文件时，也许我必须做一些特别的事情。我只是使用：

make clean html && make html

我的conf.py位于：root/source/conf.py。以下是我的conf.py文件的一些摘录：

import sphinx_rtd_theme

project = 'Project Name'
copyright = '2021, My Company'
author = 'My Name, Coworker Name'
master_doc = 'Home'
extensions = ["sphinx_rtd_theme", "sphinx.ext.todo"]
todo_include_todos = True
templates_path = ['_templates']
source_suffix = ['.rst']
html4_writer = True
html_theme = 'sphinx_rtd_theme'
# html_theme_path = ['_static']
html_static_path = ['_static']
# html_extra_path = []
html_show_sphinx = True
html_show_copyright …

我正在第一次使用 Sphinx 进行一个项目，并想创建一个方法（我不确定这是否是它的名字，但类似于编程方法，只是执行特定任务的文本正文）来更改我的 Sphinx 项目中的字体。我发现了一个有用的问题，可以让我在这里更改文本的颜色。

下面用于更改颜色的代码。

.. raw:: html

    <style> .red {color:red} </style>

之后，我简单地添加了

.. role:: red

对于我的 .rst 文件，允许我通过简单地使用来调用此方法

:red:`Text here is red.`

同样，我试图这样做是为了在需要时更改文本的字体，而不是整个项目的字体。这是我的调整版本。

.. raw:: html

    <p style="font-family:'Courier New'"> .font </p>

.. role:: font

这有效，有点......在我使用“make html”编译后，我的html页面只会显示新字体中的“.font”，当我尝试调用

:font:`new font here`

和以前一样，它不会改变文本。

任何有关如何使其正常工作的建议将不胜感激。谢谢。

我正在使用 Sphinx 构建 Python 包的文档。

我有一个API.rst文件，其中列出了我的函数，如下所示：.. autofunction:: mymodule.foo.bar1

对于此页面自动记录的不同功能，我可以输入以下内容：

:func:`foo1` 

在 的文档字符串中foo2()，它将创建到第一个函数的链接。

但是，如果我有第二个文件API2.rst，其中我自动记录了一些其他函数，则相同的语法似乎无法找到不同页面之间的链接。甚至See Also功能也没有链接。

有没有办法跨页面指定和链接不同的功能？谢谢

例子

• 可以在此处找到该存储库的文档
• 例如，在此函数的文档字符串中，在参数下peaks，我尝试链接到另一个名为的函数ecg_peaks()，该函数在此处记录