Making numbered lists in reStructuredText

Question

How can I make a numbered list in reStructuredText where each item is a link to some corresponding text below? For example for use in an "FAQ" page, where the questions are listed and numbered as hyperlinks and each question's link leads to its answer below on the page. For example:

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

In HTML this can be done with hrefs and the # symbol, but I'm wondering what is the equivalent reStructuredText syntax?

Answer 1

A good example to start with is the Docutils FAQ (reStructuredText was developed along side Docutils and Sphinx is simply an extension of Docutils). Here the FAQ is constructed simply with section headings and the table of contents directive (see the reStructuredText source, link at the bottom of the page).

You say in a comment that you already have a table of contents on your page, so want you want is a second table of contents which is local to the FAQ section. This can be done with the :local: option to the contents directive. Try out the following example to see this local table of contents in action:

=======================================
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...

Answer 2

See enumerated lists and internal hyperlink targets in the first Google result for "restructuredtext list". You can combine these like so:

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

.. _question 1:
the answer to question 1

For backreferences per your comment, you can use "inline internal targets", which the quick reference mentions but only the full reference actually describes. Unfortunately, it seems to be impossible for the same text to be both a link and a target (even if the syntax technically allowed it, it would be ambiguous), so you would need more text in the list item than just the question. Your best way might be to have each question link back to the list rather than to a particular list item - eg,

.. _List of questions:
...

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