[python-sphinx] 다른 페이지의 부제목 또는 앵커에 상호 참조 추가

Program / 글쓴이

reST / Sphinx 페이지의 상호 참조를 동일한 문서 세트의 다른 페이지에있는 하위 헤더 또는 앵커에 삽입하는 방법은 무엇입니까?

답변

“reST / Sphinx”라는 표현은 질문의 범위를 명확하지 않게 만듭니다. 그것은 일반적으로 reStructuredText에 대한인가 와 스핑크스, 또는 단지 reStructuredText 약 에 사용되는 스핑크스 (그리고 일반적으로 reStructuredText)? RST를 사용하는 사람들은 어느 시점에서 두 가지 경우에 모두 부딪 칠 가능성이 있으므로 두 가지를 모두 다룰 것입니다.

스핑크스

클래스 ( :class:) 와 같은 다양한 엔티티에 링크하는 데 사용할 수있는 도메인 별 지시문 외에도 여기:ref: 에 문서화 된 일반 지시문이 있습니다 . 그들은이 예를 제공합니다.

    .. _my-reference-label:

    Section to cross-reference
    --------------------------

    This is the text of the section.

    It refers to the section itself, see :ref:`my-reference-label`.

RST에서 제공하는 일반적인 하이퍼 링크 메커니즘은 Sphinx에서 작동하지만 문서에서는 Sphinx를 사용할 때 사용하지 말 것을 권장합니다.

ref를 사용하는 것은 섹션에 대한 표준 reStructuredText 링크 (예 : Section title_) 를 사용하는 것이 좋습니다. 이는 파일간에, 섹션 제목이 변경 될 때 및 상호 참조를 지원하는 모든 빌더에 대해 작동하기 때문입니다.

RST, 일반

RST 파일을 HTML로 변환하는 도구에는 반드시 컬렉션 개념이있는 것은 아닙니다 . 예를 들어 github를 사용하여 RST 파일을 HTML로 변환하거나 rst2html. 불행히도 원하는 결과를 얻기 위해 사용하는 다양한 방법은 사용중인 도구에 따라 다릅니다. 예를 들어, rst2html파일 A.rst을 사용 하고 파일 에서 “섹션”이라는 섹션에 파일 을 연결 other.rst하고 최종 HTML이 브라우저에서 작동하도록하려면 다음 A.rst을 포함합니다.

`This <other.html#section>`__ is a reference to a section in another
file, which works with ``rst2html``. Unfortunately, it does not work
when the HTML is generated through github.

최종 HTML 파일에 링크 id해야하며 섹션에 제공되는 내용을 알아야 합니다. github를 통해 제공되는 파일에 대해 동일한 작업을 수행하려면 다음을 수행하십시오.

`This <other.rst#section>`__ is a reference to a section in another
file, which works on github. Unfortunately, it does not work when you
use ``rst2html``.

여기에서도 id섹션에 주어진 것을 알아야합니다 . 그러나 HTML이 작성되는 RST 파일에 액세스 할 때만 가능하기 때문에 RST 파일에 링크합니다. (이 답변을 작성하는 시점에서 HTML에 직접 액세스하는 것은 허용되지 않습니다.)

완전한 예는 여기에서 볼 수 있습니다 .

답변

2016 년 새롭고 더 나은 답변!

autosection 확장은 쉽게이 작업을 수행 할 수 있습니다.

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


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

그럼 나중에 …

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


A link-  :ref:`Internal Headline`

이 확장 기능은 내장되어 있으므로 편집 만하면됩니다. conf.py

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

주의해야 할 유일한 사항은 이제 문서 컬렉션에서 내부 헤드 라인을 복제 할 수 없다는 것입니다. (그럴 가치가 있습니다.)

답변

예:

Hey, read the :ref:`Installation:Homebrew` section.

Homebrew라는 다른 문서 내의 섹션은 어디에 있습니까 Installation.rst?

이것은 자동 섹션 기능을 사용하므로 다음을 사용하여 편집해야합니다 config.py.

extensions = [
    'sphinx.ext.autosectionlabel'
]
autosectionlabel_prefix_document = True

답변