在 reStructuredText 中制作编号列表答案

【问题标题】：Making numbered lists in reStructuredText在 reStructuredText 中制作编号列表
【发布时间】：2012-06-02 00:37:38
【问题描述】：

如何在 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 语法是什么？

【问题讨论】：

this 是您正在寻找的东西吗？
看起来不像，除非我遗漏了一些东西。我的文档中已经有一个目录，我希望其中一个部分有这种超链接列表......非常微不足道，只是编号的项目链接到下面的相应部分。我是否需要将列表中的每个项目都设为一个部分并在文档中添加第二个目录？这就是你提议的吗？谢谢

标签： python python-sphinx restructuredtext

【解决方案1】：

一个很好的例子是Docutils FAQ（reStructuredText 是与 Docutils 一起开发的，Sphinx 只是 Docutils 的扩展）。此处的常见问题解答仅由部分标题和table of contents directive 构成（请参阅reStructuredText 源代码，页面底部的链接）。

您在评论中说您的页面上已经有一个目录，因此您需要第二个目录，该目录位于常见问题解答部分的本地。这可以通过contents 指令的:local: 选项来完成。试试下面的例子，看看这个本地目录的实际效果：

=======================================
Testing the inclusion of an FAQ section
=======================================

.. contents:: Table of Contents
   :depth: 1

Some uninteresting section
==========================

with some text...

FAQ
===

.. contents::
  :local:
  :backlinks: none
  :depth: 1

Question 1
----------

Lorem ipsum dolor sit amet...

Question 2
----------

Suspendisse tortor tellus...

Question 3
----------

Mauris in magna sed arcu semper auctor vitae eu risus...

Some other uninteresting section
================================

with some text...

【讨论】：

【解决方案2】：

请参阅“重组文本列表”的第一个 Google 搜索结果中的 enumerated lists 和 internal hyperlink targets。您可以像这样组合它们：

#. `question 1`_
#. `question 2`_

.. _question 1:
the answer to question 1

对于每条评论的反向引用，您可以使用“inline internal targets”，快速参考提到但实际上只有完整参考描述。不幸的是，同一文本似乎不可能既是链接又是目标（即使语法在技术上允许这样做，它也会模棱两可），因此列表项中需要更多的文本而不仅仅是问题。您最好的方法可能是将每个问题链接回 list 而不是特定的列表项 - 例如，

.. _List of questions:
...

.. _question 1:
the answer to question 1
`List of questions`_

【讨论】：

我认为需要.. _question 1: 才能工作。但是，这里的编号不是自动的......您需要在定义答案时输入问题 1、2 等，所以这不是一个自动解决方案，用户仍然必须跟踪问题的顺序，答案是没有反向引用这些问题。
@user248237 我添加了_，很好。在您的问题中，您要求提供 HTML 内部 href 之类的内容 - 但它们的问题与您描述的问题完全相同。您需要手动跟踪href 和target 之间的配对。
你是对的。所以假设我手动保持配对.. 我怎样才能反向引用它们，以便我在问题 1 的答案的编号列表中有一个链接，上面写着“回到问题 1”？另外，我可以将标记放在参考文献中吗？这似乎不起作用：question 1 has code`` 在里面``_
我不理解重组后的空格...如果我有.. _question 1，有时它会将“id”标签放入 HTML 中，如果我有几个，它会丢弃它们。。很奇怪。没有意义。
@user248237 .. _question 1 是一个链接 target，因此拥有多个链接是不明确的 - 有关 rst 如何解决该问题的规则，请参阅 docutils.sourceforge.net/docs/ref/rst/…。它提到的“隐含目标”也可能很有用 - 如果答案都将上面的问题作为标题，那么您可以将它们用作链接目标，而根本不需要.. _question 1。我不确定为什么它有时只会将id 放在 HTML 中 - AIUI 现在是执行链接目标的公认方式，name 被保留用于表单。