Добавление перекрестной ссылки на подзаголовок или привязку на другой странице

Как вставить перекрестную ссылку на странице reST / Sphinx в подзаголовок или привязку на другой странице в том же наборе документации?

3 65
restructuredtext python-sphinx

3 ответа:

игнорировать этот ответ, он не работает: лучше использовать ответ от Louis

для якоря, вы можете определить "короткие" имена якоря, как это:

.. _ShortAnchor:

Target Header goes here
=======================

Some text.

для ссылки на этот заголовок используйте:

For more details, see ShortAnchor_.

обратите внимание, что это даже расширяет ShortAnchor до полного имени заголовка.

вы также можете использовать полное имя заголовка, как:

See `Target Header goes here`_ chapter.

но это больше ошибка, склонная к изменению текста заголовка.

все это работает с несколькими исходными файлами, являющимися частью одной окончательной документации.

12

выражение "reST / Sphinx" делает объем вопроса неясным. Речь идет о реструктурированном тексте вообще и Сфинкс, или только о reStructuredText а в Сфинкс (а не реструктурированный текст вообще)? Я собираюсь охватить оба, так как люди, использующие RST, вероятно, столкнутся с обоими случаями в какой-то момент:

Сфинкс

помимо директив, специфичных для домена, которые могут использоваться для связи с различными сущности, такие как классы (:class:) вот и генерал

132

новый, лучший ответ на 2016 год!

The расширение автосекции позволяет сделать это легко.

=============
Some Document
=============


Internal Headline
=================

потом, позже...

===============
Some Other Doc
===============


A link-  :ref:`Internal Headline`

это расширение встроено, так что все, что вам нужно, это редактировать conf.py

extensions = [
    .
    . other
    . extensions
    . already
    . listed
    .
    'sphinx.ext.autosectionlabel',
]

единственное, что вы должны быть осторожны, это то, что теперь вы не можете дублировать внутренние заголовки в коллекции doc. (Стоить того.)

30