Skip to content

Latest commit

 

History

History
86 lines (59 loc) · 2.72 KB

autosectionlabel.rst

File metadata and controls

86 lines (59 loc) · 2.72 KB

:mod:`sphinx.ext.autosectionlabel` -- Allow referencing sections by their title

.. module:: sphinx.ext.autosectionlabel
   :synopsis: Allow referencing sections by their title.

.. versionadded:: 1.4

By default, cross-references to sections use labels (see :rst:role:`ref`). This extension allows you to instead refer to sections by their title.

For example:

A Plain Title
-------------

This is the text of the section.

It refers to the section title, see :ref:`A Plain Title`.

Internally, this extension generates the labels for each section. If same section names are used in whole of document, any one is used for a target by default. The autosectionlabel_prefix_document configuration variable can be used to make headings which appear multiple times but in different documents unique.

Use the :conf:`autosectionlabel_full_reference` configuration variable to guarantee that the generated references are unique across a document with similar section names at different levels.

Configuration

.. confval:: autosectionlabel_prefix_document
   :type: :code-py:`bool`
   :default: :code-py:`False`

   True to prefix each section label with the name of the document it is in,
   followed by a colon. For example, ``index:Introduction`` for a section
   called ``Introduction`` that appears in document ``index.rst``.  Useful for
   avoiding ambiguity when the same section heading appears in different
   documents.

.. confval:: autosectionlabel_maxdepth
   :type: :code-py:`int | None`
   :default: :code-py:`None`

   If set, autosectionlabel chooses the sections for labeling by its depth. For
   example, when set 1 to ``autosectionlabel_maxdepth``, labels are generated
   only for top level sections, and deeper sections are not labeled.  It
   defaults to ``None`` (i.e. all sections are labeled).

.. confval:: autosectionlabel_full_reference
   :type: :code-py:`bool`
   :default: :code-py:`False`

.. versionadded:: 8.2

   True to make each section label include all the parent sections separated by
   a colon. For instance, if the following appears in document ``index.rst``:

   .. code-block:: rst

      Title
      =====

      Section
      -------

      Sub Section
      ~~~~~~~~~~~

   The reference of the third level section ("Sub Section") will be
   ``index:Title:Section:Sub Section``.

Debugging

The WARNING: undefined label indicates that your reference in :rst:role:`ref` is mis-spelled. Invoking :program:`sphinx-build` with -vvv (see :option:`-v`) will print all section names and the labels that have been generated for them. This output can help finding the right reference label.