0

In documentation for many packages, including Sphinx itself, I see a directive at the start of certain files of the form

.. _<filename>:

For example, many glossaries start with

.. _glossary:

What do these directives do and where are they documented?

Note that I this is omitted from, for example, my 'glossary.rst', then :ref:glossary links to the Python glossary at python.org, rather than my glossary, so the directive is doing something important.

bad_coder
  • 11,289
  • 20
  • 44
  • 72
orome
  • 45,163
  • 57
  • 202
  • 418

1 Answers1

1

A directive such as .. _glossary: is a label that identifies a spot in the document (a link target).

A link to that spot is created with this markup: :ref:`glossary`. See http://sphinx-doc.org/markup/inline.html#ref-role for details.

And yes, if you use the intersphinx extension (configured like this: intersphinx_mapping = {'python': ('http://docs.python.org/2.7', None)}) and use the above link without having defined your own .. _glossary: label, the resulting link in the output will indeed point to http://docs.python.org/2.7/glossary.html#glossary.

mzjn
  • 48,958
  • 13
  • 128
  • 248