我正在使用 Sphinx 来记录工作项目。我想在整个文档的多个页面上使用指向下载的相同链接。

例如：home.rst：

Hi
==

I want you to download_ my project.

.. _download: blah.com/download

other_page.rst

Hello Again
===========
You can also download_ it here.

.. _download: blah.com/download

有没有某种方法可以让每个页面都指向一个变量，以便当链接需要更新时仅需要更新变量？

我知道我可以在 sphinx 中记录（模块）常量

#: a tuple of primes
primes = (2, 3, 5, 7, 11, 13, 17)

或者

primes =  (2, 3, 5, 7, 11, 13, 17)
"""a tuple of primes"""

然后它将出现在 sphinx 生成的文档中；即它看起来像这样：

somemodule.primes

= (2, 3, 5, 7, 11, 13, 17)

素数元组

但如果数据是一个很长的列表怎么办？那么我希望能够在文档中包含文档字符串，但在文档中不包含实际数据本身。

这就是我想要在文档中包含的内容：

somemodule.primes

素数元组

有什么方法可以实现这个目标吗？

为了完整性：

我运行sphinx-quickstart并启用了 autodoc：

autodoc: automatically insert docstrings from modules (y/n) [n]: y

我唯一添加的index.rst是：

``somemodule``
**************

.. automodule:: somemodule
    :members:

并somemodule.py包含这个：

#: a tuple …

我是 sphinx 的新手，需要帮助找出为什么出现以下错误：

WARNING: autodoc: failed to import module 'employe_dao' from module 'models'; the following exception was raised:
No module named 'models'

我的项目结构是：

|--master_project
   |--sub_project
      |--docs
        |--build
        |--conf.py
        |--index.rst
        |--Makefile
        |--models.rst
        |--src.models.rst
        |--src.rst
      |--src
        |--models
          |--employee.py
          ...
        |--__init__.py
        |--data_extractor.py
        |--optimiser.py
    enter code here
        ...

这是来自的片段index.rst

...

.. toctree::
   :maxdepth: 2
   :caption: Contents:

.. automodule::src
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule::models
   :members:
   :undoc-members:
   :show-inheritance:

...

* :ref:`modindex`

我已按照 Sphinx 中的建议添加sys.path.insert(0, os.path.abspath('./sub_project'))并取消注释： autodoc can`t import moduleimport os, import …

我有一个 Sphinx 项目，其中包含一组文件，其中每个文件底部包含外部链接作为引用，如下所示：

Some text with `my link`_, more text
100 lines of text ...

.. _my link: http://example.com

我想重新组织我的文件，拆分它们，合并它们并重新使用外部链接。为了使这更容易，我想将我的链接保存在一个单独的文件中，每个链接都有一个我可以在文本中引用的唯一 ID。有没有办法做到这一点？渲染的输出仍应创建外部链接，而不是像如何收集 Sphinx 中的所有外部链接？中建议的脚注。

考虑以下情况：

.. code-block:: my_lang

    ...

如果我想让 my_lang 像Python这样的东西，我该怎么做？

我想让访问者能够对使用 python-sphinx 从 RST 生成的 HTML 页面中的表格中的单元格进行排序。假设我有一个这样的表：

.. list-table:: A fancy name table
   :header-rows: 1
   
   * - Family name
     - Given name
   * - Smith
     - Samuel
   * - Johnson
     - John

这可以很好地呈现并按输入顺序显示名称。现在我想生成一个 HTML 输出，并为用户提供将名称重新排序为字母顺序的可能性。有独立的示例和库来实现这一点，我想知道哪种解决方案已经在 Sphinx 中实现（如果有）。最好的方法是包含一个最小的扩展并修改所有表（或只是我希望能够排序的表）的属性以包含此功能。

您能否建议扩展以及如何做到这一点的最佳实践？我更愿意自己进行尽可能少的 CSS 和 JS 代码/文件操作。

我将Sphinx与“阅读文档”主题一起使用。对于小型内联代码片段，例如在一段文本中提及单个变量，我使用双反引号将代码格式化为文档中所谓的“内联文字”。

1. 这是格式化内联代码片段的正确方法吗？

与正确的代码块不同，内联代码片段不会执行特定于语言的语法突出显示（这很好）。如上面的链接文档所示（请参见下面的屏幕截图），所有此类“内联文字”都被涂成红色。

2. 我怎样才能把这个颜色变成别的颜色？

我只关心 Sphinx 的 HTML 输出。

我正在尝试使用呼吸将 doxygen 和 sphinx 缝合在一起。

Breath 要求您首先生成 doxygen xml 输出：https ://breathe.readthedocs.io/en/latest/quickstart.html

我不想在单独的步骤中执行此操作。我可以在构建时为我sphinx-build执行吗？doxygen我只需要它先使用一些参数运行此命令。无需编写自定义 sphinx 插件就可以实现这一点吗？

编辑

这有效

# Need to sleep because sometimes doxygen doesnt finish writing files before sphinx runs 
cwd = os.path.dirname(os.path.realpath(__file__))
os.system('doxygen')
time.sleep(3)

我正在使用Sphinx的"手动"文档类,我对Latex输出的外观非常满意,除了页眉.它包含我的论文标题,以及"Release 1".

由于我正在撰写论文而不是文档,因此我显然不需要发布信息.不幸的是,很难找到有关如何定制Sphinx乳胶输出的信息.

有人知道怎么做吗？

如何在reStructuredText中创建一个编号列表,其中每个项目都是下面某些相应文本的链接？例如,在"常见问题"页面中使用,其中问题被列出并编号为超链接,并且每个问题的链接在页面下面引出其答案.例如:

1. question 1 [links to #1 below]
2. question 2 [links to #2 below]
3. question 3 [links to #3 below]
4. ...

#1 question 1:
the answer to question 1

#2 question 2:
the answer to question 2

#3 question 3:
the answer to question 3

在HTML中,这可以用hrefs和#符号完成,但我想知道什么是等效的reStructuredText语法？