reStructuredText 마크업

이 문서는 Python 문서화를 지원하기 위해 Sphinx가 도입한 사용자 정의 reStructuredText 마크업과 그 사용 방법을 설명합니다.

빠른 참조

이 표는 자주 사용되는 몇 가지 요소에 어떤 마크업을 사용해야 하는지 요약합니다:

요소	마크업	더 보기
인자/매개변수	*arg*	인라인 마크업
변수/리터럴/코드	``foo``, ``42``, ``len(s) - 1``	인라인 마크업
True/False/None	``True``, ``False``, ``None``	인라인 마크업
함수 정의	.. function:: print(*args)	Directives
함수 참조	:func:`print`	Roles
어트리뷰트 정의	.. attribute: `attr-name`	정보 단위
어트리뷰트 참조	:attr:`attr-name`	Roles
참조 레이블	.. _label-name:	상호 링크 마크업
내부 참조	:ref:`label-name`	상호 링크 마크업
외부 링크	`Link text <https://example.com>`__	Hyperlinks
사용자 정의 텍스트를 사용하는 역할	:role:`custom text <target>`	Roles
마지막 부분만 표시하는 역할	:role:`~hidden.hidden.visible`	Roles
링크가 없는 역할	:role:`!target`	Roles
이슈	:gh:`ID`, :issue:`ID`	Roles
CPython 소스	:source:`PATH`	Roles
주석	.. a comment	Comments

reStructuredText 입문

이 절에서는 작성자가 문서를 효율적으로 작성하는 데 충분한 정보를 제공하기 위해 reStructuredText(reST)의 개념과 문법을 간략히 소개합니다. reST는 단순하고 눈에 거슬리지 않는 마크업 언어로 설계되었으므로 오래 걸리지 않을 것입니다.

더 보기

공식 reStructuredText 사용자 문서입니다.

공백 사용

모든 reST 파일은 3칸 들여쓰기를 사용하며, 탭은 허용되지 않습니다. 일반 텍스트의 최대 줄 길이는 80자이지만, 표, 깊게 들여쓴 코드 예제, 긴 링크는 이를 넘을 수 있습니다. 코드 예제 본문에는 일반적인 Python 4칸 들여쓰기를 사용해야 합니다.

적절한 곳에 빈 줄을 여러 개 사용하여 reST 파일의 구조를 명확하게 하십시오. 빈 줄을 추가하면 섹션을 묶을 수 있어 파일의 구성이 더 명확해집니다.

문장을 끝맺는 마침표 뒤에는 공백을 하나 또는 두 개 둘 수 있습니다. reST는 두 번째 공백을 무시하지만, 일부 사용자는 Emacs의 auto-fill 모드에 도움이 되도록 하는 등의 이유로 관례적으로 두 번째 공백을 넣습니다.

문단

문단은 reST 문서에서 가장 기본적인 블록입니다. 문단은 하나 이상의 빈 줄로 구분된 텍스트 덩어리일 뿐입니다. Python과 마찬가지로 reST에서도 들여쓰기가 중요하므로, 같은 문단의 모든 줄은 같은 들여쓰기 수준에 맞춰 왼쪽 정렬해야 합니다.

인라인 마크업

표준 reST 인라인 마크업은 매우 간단합니다. 다음을 사용하십시오:

• 별표 하나: 강조(이탤릭체)에는 *text*,

• 별표 두 개: 강한 강조(굵은 글씨)에는 **text**, 그리고

• 역따옴표: 코드 예제, 변수, 리터럴에는 ``text``.

본문에 나오는 별표나 역따옴표가 인라인 마크업 구분자와 혼동될 수 있다면 백슬래시로 이스케이프해야 합니다.

이 마크업에는 몇 가지 제약이 있다는 점에 유의하십시오:

• 중첩할 수 없습니다,

• 내용은 공백으로 시작하거나 끝날 수 없습니다: * text*는 잘못된 형식입니다,

• 주변 텍스트와는 단어가 아닌 문자로 구분되어야 합니다. 이를 우회하려면 백슬래시로 이스케이프한 공백을 사용하십시오: thisis\ *one*\ word.

이러한 제약은 향후 버전의 docutils에서 해제될 수 있습니다.

reST는 사용자 정의 “해석 텍스트 역할(interpreted text roles)”도 지원합니다. 이는 감싼 텍스트를 특정한 방식으로 해석해야 함을 나타냅니다. Sphinx는 해당 섹션에서 설명하는 것처럼 이를 사용하여 의미론적 마크업과 식별자 상호 참조를 제공합니다. 일반적인 문법은 :rolename:`content`입니다.

목록과 인용문

목록 마크업은 자연스럽습니다. 문단의 시작 부분에 별표를 놓고 적절히 들여쓰기만 하면 됩니다. 번호 목록도 마찬가지이며, # 기호를 사용하여 번호를 자동으로 매길 수도 있습니다:

* This is a bulleted list.
* It has two items, the second
  item uses two lines.

1. This is a numbered list.
2. It has two items too.

#. This is a numbered list.
#. It has two items too.

중첩 목록도 가능하지만, 상위 목록 항목과는 빈 줄로 구분해야 한다는 점에 유의하십시오:

* this is
* a list

  * with a nested list
  * and some subitems

* and here the parent list continues

정의 목록은 다음과 같이 만듭니다:

term (up to a line of text)
   Definition of the term, which must be indented

   and can even consist of multiple paragraphs

next term
   Description.

문단을 주변 문단보다 더 들여쓰기만 하면 인용문이 됩니다.

소스 코드

리터럴 코드 블록은 문단을 특수 표식 ::로 끝내면 시작됩니다. 리터럴 블록은 들여쓰기해야 합니다:

This is a normal text paragraph. The next paragraph is a code sample::

   It is not processed in any way, except
   that the indentation is removed.

   It can span multiple lines.

This is a normal text paragraph again.

:: 마커는 영리하게 처리됩니다:

• 마커가 단독으로 한 문단을 이루면 그 문단은 문서에서 완전히 제외됩니다.

• 마커 앞에 공백이 있으면 마커가 제거됩니다.

• 마커 앞에 공백이 아닌 문자가 있으면 마커는 콜론 하나로 바뀝니다.

이렇게 하여 위 예제의 첫 번째 문단에 있는 두 번째 문장은 “The next paragraph is a code sample:”로 렌더링됩니다.

하이퍼링크

외부 링크

인라인 웹 링크에는 `Link text <https://example.com>`__를 사용하십시오. 링크 텍스트가 웹 주소 그 자체여야 한다면 특별한 마크업이 전혀 필요하지 않습니다. 파서가 일반 텍스트에서 링크와 메일 주소를 찾아냅니다. 대상 이름 충돌을 피하려면 (밑줄 하나를 쓰는) 이름 있는 하이퍼링크보다 (밑줄 두 개를 쓰는) 익명 하이퍼링크를 사용하십시오.

내부 링크

내부 링크는 특별한 reST 역할(role)을 사용하여 만듭니다. 특정 마크업에 관한 절(상호 링크 마크업)을 참조하십시오.

절

섹션 제목 아래에 구두점 문자로 밑줄을 그어(선택적으로 윗줄도 그어) 섹션 헤더를 만들며, 이 줄은 최소한 텍스트 길이만큼 길어야 합니다:

=================
This is a heading
=================

일반적으로 구조는 제목이 나오는 순서에 따라 결정되므로 특정 문자에 할당된 제목 수준은 없습니다. 하지만 Python 문서에서는 다음과 같은 규칙을 권장합니다:

• 부(part)에는 윗줄을 함께 쓰는 #

• 장(chapter)에는 윗줄을 함께 쓰는 *

• 절에는 =

• 하위 절에는 -

• 하위의 하위 절에는 ^

• 문단에는 "

명시적 마크업

reST에서는 각주, 특별히 강조된 단락, 주석, 일반 지시문처럼 특별한 처리가 필요한 대부분의 구성 요소에 “명시적 마크업”을 사용합니다.

명시적 마크업 블록은 .. 다음에 공백이 오는 줄로 시작하며, 들여쓰기 수준이 같은 다음 문단에서 끝납니다. (명시적 마크업과 일반 문단 사이에는 빈 줄이 있어야 합니다. 모두 조금 복잡하게 들릴 수 있지만, 실제로 작성해 보면 충분히 직관적입니다.)

지시문

지시문은 명시적 마크업의 일반적인 블록입니다. 역할과 더불어 reST의 확장 메커니즘 중 하나이며, Sphinx는 이를 매우 많이 사용합니다.

기본적으로 지시문은 이름, 인자, 옵션, 내용으로 구성됩니다. (이 용어를 기억해 두십시오. 사용자 정의 지시문을 설명하는 다음 섹션에서 사용됩니다.) 다음 예를 살펴보면,

.. function:: foo(x)
              foo(y, z)
   :bar: no

   Return a line of text input from the user.

function은 지시문 이름입니다. 여기에는 인자 두 개(첫 번째 줄의 나머지 부분과 두 번째 줄)와 옵션 bar 하나가 주어집니다(보시는 것처럼 옵션은 인자 바로 다음 줄에 주어지며 콜론으로 표시됩니다).

지시문 내용은 빈 줄 다음에 오며, 지시문 시작 위치를 기준으로 들여쓰기됩니다.

각주

각주 위치는 [#]_로 표시하고, 각주 본문은 다음과 같이 문서 하단의 “Footnotes” 루브릭 제목 뒤에 추가하십시오:

Lorem ipsum [#]_ dolor sit amet ... [#]_

.. rubric:: Footnotes

.. [#] Text of the first footnote.
.. [#] Text of the second footnote.

맥락을 더 명확히 하기 위해 각주에 번호를 명시적으로 매길 수도 있습니다.

주석

유효한 마크업 구성 요소가 아닌 모든 명시적 마크업 블록(.. 로 시작하는 블록)은 주석으로 간주되며, 이 블록에는 리터럴 텍스트를 담을 수 있습니다:

.. This is a comment

소스 인코딩

reST에 엠 대시나 저작권 기호 같은 특수 문자를 넣는 가장 쉬운 방법은 유니코드 문자로 직접 작성하는 것이므로, 인코딩을 지정해야 합니다:

모든 Python 문서 소스 파일은 UTF-8 인코딩이어야 하며, 이로부터 작성되는 HTML 문서도 같은 인코딩을 사용합니다.

주의할 점

reST 문서를 작성할 때 흔히 마주치는 몇 가지 문제가 있습니다:

• 인라인 마크업의 분리: 앞서 말했듯이 인라인 마크업 범위는 단어가 아닌 문자로 주변 텍스트와 분리되어야 하며, 이를 우회하려면 이스케이프된 공백을 사용해야 합니다.

조판 규칙

빅 O 표기법

빅 O 표기법은 알고리즘의 성능을 설명하는 데 사용됩니다.

빅 O와 변수에는 이탤릭체를 사용하십시오. 예를 들면 다음과 같습니다:

reStructuredText	렌더링 결과
*O*\ (1)	O(1)
*O*\ (log *n*)	O(log n)
*O*\ (*n*)	O(n)
*O*\ (*n* log *n*)	O(n log n)
*O*\ (*n*\ :sup:`2`)	O(n2)

추가 마크업 구성 요소

Sphinx는 표준 reST 마크업에 많은 새로운 지시문과 해석 텍스트 역할을 추가합니다. 이 절에는 이러한 기능에 대한 참조 자료가 있습니다. “표준” reST 구성 요소는 Python 문서에서 사용되지만, 여기서는 해당 문서를 다루지 않습니다.

참고

이것은 Sphinx의 확장 마크업 기능에 대한 개요일 뿐이며, 전체 내용은 Sphinx 자체 문서에서 확인할 수 있습니다.

모듈 관련 마크업

이 절에서 설명하는 마크업은 문서화되는 모듈에 대한 정보를 제공하는 데 사용됩니다. 각 모듈은 자체 파일에 문서화해야 합니다. 일반적으로 이 마크업은 해당 파일의 제목 뒤에 나타나며, 전형적인 파일은 다음과 같이 시작할 수 있습니다:

:mod:`!parrot` -- Dead parrot access
====================================

.. module:: parrot
   :synopsis: Analyze and reanimate dead parrots.

module

이 지시문은 모듈, 패키지 또는 하위 모듈에 대한 설명의 시작을 표시합니다. 이름은 완전히 정규화된 이름이어야 합니다(즉, 서브 모듈의 경우 패키지 이름을 포함해야 합니다).

synopsis 옵션은 모듈의 목적을 설명하는 한 문장으로 구성해야 합니다 – 현재는 전역 모듈 색인에서만 사용됩니다.

deprecated 옵션을 (값 없이) 지정하여 모듈을 폐지 예정으로 표시할 수 있으며, 그러면 여러 위치에서 해당 모듈이 폐지 예정으로 표시됩니다.

참고

모듈을 설명하는 파일의 섹션 제목은 개요 파일의 목차 트리에 삽입되므로 의미 있게 짓는 것이 중요합니다.

정보 단위

모듈이 제공하는 특정 기능을 설명하는 데 사용하는 지시문이 여럿 있습니다. 각 지시문에는 설명 대상에 대한 기본 정보를 제공하는 시그니처가 하나 이상 필요하며, 내용에는 설명이 들어가야 합니다. 기본 버전은 일반 색인에 항목을 만듭니다. 색인 항목을 원하지 않으면 지시문 옵션 플래그 :noindex:를 지정할 수 있습니다. 다음 예는 이 지시문 유형의 모든 기능을 보여줍니다:

.. function:: spam(eggs)
              ham(eggs)
   :noindex:

   Spam or ham the foo.

객체 메서드나 데이터 어트리뷰트의 시그니처에는 클래스 이름을 포함하지 말고, 클래스 지시문 안에 중첩해야 합니다. 생성된 파일에는 이 중첩 구조가 반영되며, 일관된 상호 참조가 가능하도록 (HTML 출력의) 대상 식별자에는 클래스 이름과 메서드 이름이 모두 사용됩니다. 컨텍스트 관리자와 같은 추상 프로토콜에 속하는 메서드를 설명하는 경우에도 (의사) 타입 이름으로 클래스 지시문을 사용하여 색인 항목이 더 많은 정보를 담도록 하십시오.

지시문은 다음과 같습니다:

c:function

C 함수를 설명합니다. 시그니처는 C에서와 같이 작성해야 합니다. 예를 들면 다음과 같습니다:

.. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)

함수와 비슷한 전처리기 매크로를 설명할 때도 사용합니다. 설명에서 사용할 수 있도록 인자의 이름을 지정해야 합니다.

시그니처는 reST 인라인 파서가 해석하지 않으므로 시그니처 안의 별표를 백슬래시로 이스케이프할 필요가 없습니다.

c:member

C 구조체 구성원을 설명합니다. 시그니처 예:

.. c:member:: PyObject* PyTypeObject.tp_bases

설명 본문에는 허용되는 값의 범위, 값을 해석하는 방법, 값을 변경할 수 있는지를 포함해야 합니다. 본문에서 구조체 구성원을 참조할 때는 member 역할을 사용해야 합니다.

c:macro

“단순한” C 매크로를 설명합니다. 단순 매크로는 코드 확장에 사용되지만 인자를 받지 않으므로 함수로 설명할 수 없는 매크로입니다. 단순한 상수 정의에는 이 지시자를 사용하지 않습니다. Python 문서에서 이 매크로가 사용된 예로는 PyObject_HEAD와 Py_BEGIN_ALLOW_THREADS가 있습니다.

c:type

C 타입을 설명합니다. 시그니처에는 타입 이름만 작성해야 합니다.

c:var

전역 C 변수를 설명합니다. 시그니처에는 타입을 포함해야 합니다. 예를 들면 다음과 같습니다:

.. c:var:: PyObject* PyClass_Type

data

변수와 “정의된 상수”로 사용되는 값을 모두 포함하여 모듈의 전역 데이터를 설명합니다. 클래스와 객체 어트리뷰트는 이 지시문으로 문서화하지 않습니다.

exception

예외 클래스를 설명합니다. 시그니처에 생성자 인자가 담긴 괄호를 포함할 수 있지만, 반드시 포함할 필요는 없습니다.

function

모듈 수준 함수를 설명합니다. 시그니처에는 매개변수를 포함해야 하며, 선택적 매개변수는 대괄호로 묶어야 합니다. 명확성을 높인다면 기본값을 표기할 수 있습니다. 예를 들면 다음과 같습니다:

.. function:: repeat([repeat=3[, number=1000000]])

객체 메서드는 이 지시문으로 문서화하지 않습니다. 모듈의 공개 인터페이스의 일부로 모듈 네임스페이스에 배치된 바인딩된 객체 메서드는 대부분의 용도에서 일반 함수와 동등하므로 이 지시자로 문서화합니다.

설명에는 필요한 매개변수와 그 사용 방식(특히 매개변수로 전달된 가변 객체가 수정되는지 여부), 부작용, 발생할 수 있는 예외에 관한 정보를 포함해야 합니다. 간단한 예제를 제공할 수 있습니다.

coroutinefunction

모듈 수준 코루틴을 설명합니다. 설명에는 function에 대해 설명한 것과 비슷한 정보를 포함해야 합니다.

decorator

데코레이터 함수를 설명합니다. 시그니처는 실제 함수의 시그니처가 아니라 데코레이터로서의 사용법을 나타내야 합니다. 예를 들어 다음과 같은 함수가 있다고 가정합니다

def removename(func):
    func.__name__ = ''
    return func

def setnewname(name):
    def decorator(func):
        func.__name__ = name
        return func
    return decorator

설명은 다음과 같아야 합니다:

.. decorator:: removename

   Remove name of the decorated function.

.. decorator:: setnewname(name)

   Set name of the decorated function to *name*.

이 지시문으로 마크업된 데코레이터에 링크하려면 :deco: 역할을 사용하십시오.

class

클래스를 설명합니다. 시그니처에는 생성자 인자로 표시될 매개변수를 괄호와 함께 포함할 수 있습니다.

attribute

객체 데이터 어트리뷰트를 설명합니다. 설명에는 예상되는 데이터의 타입과 데이터를 직접 변경할 수 있는지 여부에 관한 정보를 포함해야 합니다. 이 지시문은 다음 예처럼 클래스 지시문 안에 중첩되어야 합니다:

.. class:: Spam

   Description of the class.

   .. attribute:: ham

      Description of the attribute.

어트리뷰트를 참조하려면 :attr: 역할을 사용하십시오:

Use the :attr:`ham` attribute to spam the eggs.

예를 들어 여러 어트리뷰트와 메서드에 대한 문서가 여러 섹션으로 나뉘어 있는 경우처럼, 클래스 지시문 밖에서 어트리뷰트를 문서화할 수도 있습니다. 이 경우에는 클래스 이름을 명시적으로 포함해야 합니다:

.. attribute:: Spam.eggs

method

객체 메서드를 설명합니다. 매개변수에 self 매개변수를 포함해서는 안 됩니다. 설명에는 function에 대해 설명한 것과 비슷한 정보를 포함해야 합니다. 이 지시문은 위의 예처럼 클래스 지시문 안에 중첩되어야 합니다.

coroutinemethod

객체 코루틴 메서드를 설명합니다. 매개변수에 self 매개변수를 포함해서는 안 됩니다. 설명에는 function에 대해 설명한 것과 비슷한 정보를 포함해야 합니다. 이 지시문은 class 지시문 안에 중첩되어야 합니다.

decoratormethod

decorator와 같지만, 메서드인 데코레이터에 사용합니다.

데코레이터 메서드는 :meth: 롤을 사용하여 참조하십시오.

staticmethod

객체의 정적 메서드를 기술합니다. 설명에는 function에 대해 기술한 것과 비슷한 정보가 포함되어야 합니다. 이 지시문은 class 지시문 안에 중첩되어야 합니다.

classmethod

객체의 클래스 메서드를 기술합니다. 매개변수에는 cls 매개변수를 포함하지 않아야 합니다. 설명에는 function에 대해 기술한 것과 비슷한 정보가 포함되어야 합니다. 이 지시문은 class 지시문 안에 중첩되어야 합니다.

abstractmethod

객체의 추상 메서드를 기술합니다. 설명에는 function에 대해 기술한 것과 비슷한 정보가 포함되어야 합니다. 이 지시문은 class 지시문 안에 중첩되어야 합니다.

opcode

Python bytecode 명령어를 기술합니다.

option

Python 명령줄 옵션이나 스위치를 기술합니다. 옵션 인자 이름은 꺾쇠괄호로 감싸야 합니다. 예:

.. option:: -m <module>

   Run a module as a script.

envvar

Python이 사용하거나 정의하는 환경 변수를 기술합니다.

이 지시문들의 범용 버전도 있습니다:

describe

이 지시문은 위에서 설명한 개별 지시문들과 같은 서식을 만들지만, 색인 항목이나 상호 참조 대상은 만들지 않습니다. 예를 들어, 이 문서의 지시문들을 설명하는 데 사용됩니다. 예:

.. describe:: opcode

   Describes a Python bytecode instruction.

코드 예제 보여주기

Python 소스 코드나 대화형 세션의 예제는 표준 reST 리터럴 블록을 사용해 나타냅니다. 리터럴 블록은 앞 문단의 끝에 있는 ::로 시작하며 들여쓰기로 범위가 구분됩니다.

대화형 세션을 나타내려면 Python 코드와 함께 프롬프트와 출력을 포함해야 합니다. 대화형 세션에는 특별한 마크업이 필요하지 않습니다. 입력이나 출력의 마지막 줄 뒤에는 프롬프트가 남아 있지 않아야 합니다. 올바른 사용 예는 다음과 같습니다:

>>> 1 + 1
2

구문 강조는 똑똑한 방식으로 처리됩니다:

• 소스 파일마다 “강조 언어”가 있습니다. 대부분의 파일이 파이썬 코드 조각을 강조해야 하므로 기본값은 'python'입니다.

• Python 강조 모드에서는 대화형 세션이 자동으로 인식되어 적절하게 강조됩니다.

• 다음과 같이 highlight 지시문을 사용해 강조 언어를 변경할 수 있습니다:

  .. highlight:: c
  

  이 언어는 다음 highlight 지시문을 만날 때까지 사용됩니다.

• code-block 지시문을 사용하면 단일 코드 블록의 강조 언어를 지정할 수 있습니다. 예를 들면 다음과 같습니다:

  .. code-block:: c
  
     #include <stdio.h>
  
     void main() {
         printf("Hello world!\n");
     }
  

• 강조 표시 언어로 일반적으로 사용하는 값은 다음과 같습니다.

  • python (기본값)

  • c

  • rest

  • none (강조 표시 없음)

• 현재 언어로 강조 표시하는 데 실패하면 해당 블록은 전혀 강조 표시되지 않습니다.

긴 축자 텍스트는 예제 텍스트를 일반 텍스트만 담은 외부 파일에 저장하여 포함할 수 있습니다. 파일은 literalinclude 지시문을 사용해 포함할 수 있습니다. 예를 들어, Python 소스 파일 example.py를 포함하려면 다음을 사용하십시오:

.. literalinclude:: example.py

파일 이름은 현재 파일의 경로를 기준으로 하는 상대 경로입니다. 문서 전용 포함 파일은 Doc/includes 하위 디렉터리에 두어야 합니다.

참고

표준 include 지시문도 있지만, 파일을 찾지 못하면 에러를 발생시킵니다. literalinclude는 에러를 발생시키는 대신 경고만 내보내므로 이쪽을 권장합니다.

역할

앞서 언급한 것처럼, Sphinx는 문서에 의미론적 마크업을 삽입하기 위해 :rolename:`content` 형식의 해석 텍스트 역할을 사용합니다.

CPython 문서에는 더 간단한 마크업을 사용해야 하는 몇 가지 흔한 경우가 있습니다.

• 함수와 메서드 인자에는 *arg* (arg로 렌더링됨)를 사용합니다.

• True/False/None에는 ``True``/``False``/``None``을 사용합니다.

• 약어와 두문자어에는 Full Spelling (abbreviation)을 사용합니다.

  :abbr: 역할은 일부 보조 기술 사용자와 모바일 사용자가 접근할 수 없는 HTML을 생성합니다.

또한 CPython 문서는 몇 가지 사용자 정의 역할을 정의합니다.

• :gh:`ID`: GitHub 이슈로 연결합니다.

• :issue:`ID`: bugs.python.com 이슈로 연결합니다.

• :oss-fuzz:`ID`: OSS-Fuzz 이슈로 연결합니다.

• :pypi:`NAME`: PyPI의 프로젝트로 연결합니다.

• :source:`PATH`: GitHub에 있는 소스 파일 경로로 연결되는 링크입니다.

상호 참조 역할을 더 다양하게 활용할 수 있게 해 주는 몇 가지 추가 기능이 있습니다.

• reST 직접 하이퍼링크에서처럼 명시적인 제목과 참조 대상을 지정할 수 있습니다. :role:`title <target>`은 target을 참조하지만, 링크 텍스트는 title이 됩니다.

• 내용 앞에 !를 붙이면 참조/하이퍼링크가 생성되지 않습니다.

• Python 객체 롤에서 내용 앞에 ~를 붙이면 링크 텍스트는 대상의 마지막 구성 요소만 표시합니다. 예를 들어 :meth:`~Queue.Queue.get`은 Queue.Queue.get을 참조하지만, 링크 텍스트로는 get만 표시합니다.

  HTML 출력에서 링크의 title 속성(마우스를 올리면 툴팁으로 표시될 수 있습니다)은 항상 전체 대상 이름이 됩니다.

• ~와 !를 함께 사용하는 것(예: :meth:`~!Queue.Queue.get`)은 지원되지 않습니다. !와 대상의 마지막 구성 요소를 사용하면 같은 결과를 얻을 수 있습니다(예: :meth:`!get`).

다음 역할은 모듈 안의 객체를 가리키며, 일치하는 식별자가 발견되면 하이퍼링크가 걸릴 수 있습니다:

mod

모듈의 이름입니다. 점으로 구분된 이름을 사용할 수 있습니다. 패키지 이름에도 이 역할을 사용해야 합니다.

func

Python 함수의 이름입니다. 점으로 구분된 이름을 사용할 수 있습니다. 가독성을 높이기 위해 역할 텍스트에 뒤따르는 괄호를 포함하지 않아야 합니다. 식별자를 검색할 때 괄호는 제거됩니다.

data

모듈 수준 변수나 상수의 이름입니다.

const

“정의된” 상수의 이름입니다. C 언어 #define이거나 변경하지 않을 것으로 의도된 Python 변수일 수 있습니다.

class

클래스 이름입니다. 점으로 구분된 이름을 사용할 수 있습니다.

meth

객체 메서드의 이름입니다. 역할 텍스트에는 타입 이름과 메서드 이름을 포함해야 합니다. 점으로 구분된 이름을 사용할 수 있습니다.

attr

객체 데이터 어트리뷰트의 이름입니다.

exc

예외의 이름입니다. 점으로 구분된 이름을 사용할 수 있습니다.

deco

데코레이터의 이름입니다. 점으로 구분된 이름을 사용할 수 있습니다.

이 마크업으로 감싼 이름에는 모듈 이름이나 클래스 이름, 또는 둘 다 포함될 수 있습니다. 예를 들어, :func:`filter`는 현재 모듈에 있는 filter라는 이름의 함수를 가리킬 수도 있고, 같은 이름의 내장 함수를 가리킬 수도 있습니다. 반면에 :func:`foo.filter`는 명확하게 foo 모듈의 filter 함수를 가리킵니다.

일반적으로 이 역할들에 쓰인 이름은 먼저 아무런 한정 없이 검색되고, 그다음에는 현재 모듈 이름을 앞에 붙여서, 그다음에는 현재 모듈 이름과 (있다면) 클래스 이름을 앞에 붙여서 검색됩니다. 이름 앞에 점을 붙이면 이 순서가 반대로 바뀝니다. 예를 들어, codecs 모듈의 문서에서 :func:`open`은 항상 내장 함수를 가리키지만, :func:`.open`은 codecs.open()을 가리킵니다.

이름이 현재 설명하고 있는 클래스의 어트리뷰트인지 판단할 때도 비슷한 휴리스틱이 사용됩니다.

---

다음 롤은 API 문서에 정의되어 있는 경우 C 언어 구성 요소에 대한 상호 참조를 만듭니다:

c:data

C 언어 변수의 이름입니다.

c:func

C 언어 함수의 이름입니다. 뒤따르는 괄호를 포함해야 합니다.

c:macro

위에서 정의한 “단순” C 매크로의 이름입니다.

c:type

C 언어 타입의 이름입니다.

c:member

위에서 정의한 대로 C 타입 구성원의 이름입니다.

---

다음 롤은 객체를 가리키지는 않지만, 상호 참조나 내부 링크를 만들 수 있습니다:

envvar

환경 변수입니다. 색인 항목이 생성됩니다.

keyword

Python 키워드의 이름입니다. 이 역할을 사용하면 해당 키워드의 문서로 연결되는 링크가 생성됩니다. True, False, None에는 이 역할을 사용하지 않고 단순 코드 마크업(``True``)을 사용합니다. 이들은 언어의 근간이므로 모든 프로그래머가 알고 있어야 하기 때문입니다.

option

Python의 명령줄 옵션입니다. 앞에 붙는 하이픈을 반드시 포함해야 합니다. 일치하는 cmdoption 지시문이 있으면 그 지시문으로 링크됩니다. 다른 프로그램이나 스크립트의 옵션에는 단순 ``code`` 마크업을 사용하십시오.

token

문법 토큰의 이름입니다(참조 설명서에서 생성 규칙 표시 사이에 링크를 만드는 데 사용됩니다).

---

다음 롤은 용어집의 용어에 대한 상호 참조를 만듭니다:

term

용어집에 있는 용어에 대한 참조입니다. 용어집은 용어와 정의로 이루어진 정의 목록을 담은 glossary 지시문을 사용해 만듭니다. 용어집이 term 마크업과 같은 파일에 있을 필요는 없으며, 실제로 Python 문서는 기본적으로 glossary.rst 파일에 하나의 전역 용어집을 둡니다.

용어집에 설명되지 않은 용어를 사용하면 빌드 중에 경고가 발생합니다.

---

다음 역할은 텍스트를 다른 스타일로 서식화하는 것 외에는 특별한 일을 하지 않습니다:

command

rm 같은 OS 수준 명령의 이름입니다.

dfn

본문에서 용어를 정의하는 부분을 표시합니다. (색인 항목은 생성되지 않습니다.)

file

파일이나 디렉터리의 이름입니다. 내용 안에서 중괄호를 사용해 “변수” 부분을 나타낼 수 있습니다. 예를 들면 다음과 같습니다:

``spam`` is installed in :file:`/usr/lib/python2.{x}/site-packages` ...

빌드된 문서에서 x는 Python 마이너 버전으로 대체된다는 것을 나타내기 위해 다르게 표시됩니다.

guilabel

대화형 사용자 인터페이스의 일부로 표시되는 레이블은 guilabel로 표시해야 합니다. 여기에는 curses나 기타 텍스트 기반 라이브러리를 사용하여 만든 것과 같은 텍스트 기반 인터페이스의 레이블도 포함됩니다. 버튼 레이블, 창 제목, 필드 이름, 메뉴와 메뉴 선택 항목의 이름, 심지어 선택 목록의 값까지 포함하여 인터페이스에서 사용되는 모든 레이블은 이 역할로 표시해야 합니다.

kbd

키 입력 시퀀스를 표시합니다. 키 시퀀스가 어떤 형태를 취하는지는 플랫폼이나 애플리케이션별 관례에 따라 달라질 수 있습니다. 관련된 관례가 없는 경우에는 새로운 사용자와 비원어민 사용자의 접근성을 높이기 위해 보조 키의 이름을 줄이지 않고 풀어 써야 합니다. 예를 들어, xemacs 키 시퀀스는 :kbd:`C-x C-f`처럼 표시할 수 있지만, 특정 애플리케이션이나 플랫폼을 언급하지 않는 경우에는 같은 시퀀스를 :kbd:`Control-x Control-f`로 표시해야 합니다.

mailheader

RFC 822 스타일 메일 헤더의 이름입니다. 이 마크업은 해당 헤더가 이메일 메시지에서 사용되고 있음을 뜻하지 않으며, 같은 “스타일”의 모든 헤더를 가리키는 데 사용할 수 있습니다. 여러 MIME 명세에서 정의한 헤더에도 사용됩니다. 헤더 이름은 실제로 흔히 쓰이는 방식 그대로 입력해야 하며, 널리 쓰이는 표기가 둘 이상이면 카멜 케이스 관례를 따르는 것이 좋습니다. 예: :mailheader:`Content-Type`.

makevar

make 변수의 이름입니다.

manpage

섹션을 포함한 Unix 매뉴얼 페이지에 대한 참조입니다(예: :manpage:`ls(1)`).

menuselection

메뉴 선택은 menuselection 역할을 사용하여 표시해야 합니다. 이 역할은 하위 메뉴 선택과 특정 작업 선택을 포함하는 전체 메뉴 선택 순서나 그 순서의 일부를 표시하는 데 사용됩니다. 개별 선택 항목의 이름은 -->로 구분해야 합니다.

예를 들어 “Start > Programs” 선택을 표시하려면 다음 마크업을 사용하십시오:

:menuselection:`Start --> Programs`

일부 운영 체제에서 명령이 대화 상자를 연다는 것을 나타내려고 붙이는 줄임표처럼 뒤에 붙는 표시가 있는 선택 항목을 포함할 때는 선택 항목 이름에서 그 표시를 생략해야 합니다.

mimetype

MIME 유형의 이름 또는 MIME 유형의 구성 요소(주 부분이나 부 부분만 따로 떼어 낸 것)입니다.

newsgroup

유즈넷 뉴스그룹의 이름입니다.

program

실행 프로그램의 이름입니다. 플랫폼에 따라 실행 파일의 파일 이름과 다를 수 있습니다. 특히 Windows 프로그램에서는 .exe(또는 기타) 확장자를 생략해야 합니다.

regexp

정규식입니다. 따옴표는 포함하지 않아야 합니다.

samp

코드와 같은 리터럴 텍스트 조각입니다. 내용 안에서는 :file:처럼 중괄호를 사용해 “변수” 부분을 나타낼 수 있습니다.

“변수 부분” 표시가 필요하지 않다면 대신 표준 ``code``를 사용하십시오.

다음 역할은 외부 링크를 생성합니다:

cve

Common Vulnerabilities and Exposures 항목으로 연결되는 링크입니다. :cve:`number#anchor`를 사용하여 특정 섹션으로 링크할 수 있습니다.

cwe

Common Weakness Enumeration 항목으로 연결되는 링크입니다. :cwe:`number#anchor`를 사용하여 특정 섹션으로 링크할 수 있습니다.

pep

Python 개선 제안에 대한 참조입니다. 이 역할은 적절한 색인 항목을 생성합니다. “PEP number“라는 텍스트가 생성되며, HTML 출력에서 이 텍스트는 지정된 PEP의 온라인 사본으로 연결되는 하이퍼링크가 됩니다. 이러한 하이퍼링크로 매뉴얼에서 언어를 제대로 문서화하는 일을 대신해서는 안 됩니다.

rfc

인터넷 RFC(Request for Comments)에 대한 참조입니다. 이 역할은 적절한 색인 항목을 생성합니다. “RFC 번호“라는 텍스트가 생성되며, HTML 출력에서 이 텍스트는 지정된 RFC의 온라인 사본으로 연결되는 하이퍼링크가 됩니다.

하이퍼링크를 포함하기 위한 특별한 역할은 없다는 점에 유의하십시오. 그 목적으로는 표준 reST 마크업을 사용할 수 있기 때문입니다.

상호 링크 마크업

문서의 임의 섹션에 대한 상호 참조를 지원하기 위해 표준 reST 레이블을 약간 “남용”합니다. 모든 레이블은 섹션 제목 앞에 와야 하며, 모든 레이블 이름은 전체 문서 소스에서 고유해야 합니다.

그런 다음 :ref:`label-name` 역할을 사용하여 해당 레이블로 이 섹션들을 참조할 수 있습니다.

예:

.. _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`.

:ref: 호출은 섹션 제목으로 대체됩니다.

또는 링크 텍스트 :ref:`link text <reference-label>`를 제공하면 섹션 제목뿐만 아니라 모든 레이블을 참조할 수 있습니다.

문단 수준 마크업

이 지시문들은 짧은 문단을 만들며, 일반 텍스트뿐 아니라 정보 단위 안에서도 사용할 수 있습니다:

availability

이 지시문은 모듈이나 기능을 사용할 수 있는 플랫폼을 문서화합니다. 예를 들면 다음과 같습니다:

.. availability:: Unix, not WASI, not Android.

.. availability:: Linux >= 3.0 with glibc >= 2.14.

note

노트가 관련된 API 부분을 사용할 때 사용자가 알아야 하는, API에 관한 특히 중요한 정보입니다. 지시문의 내용은 완전한 문장으로 작성하고 적절한 문장 부호를 모두 포함해야 합니다.

예:

.. note::

   This function is not suitable for sending spam e-mails.

warning

경고가 관련된 API 부분을 사용할 때 사용자가 알아야 하는, API에 관한 중요한 정보입니다. 지시문의 내용은 완전한 문장으로 작성하고 적절한 문장 부호를 모두 포함해야 합니다. 경고로 가득 찬 페이지 때문에 사용자가 떠나지 않도록, 이 지시문은 충돌, 데이터 손실 또는 보안 영향의 가능성에 관한 정보에 대해서만 note 대신 선택해야 합니다.

versionadded

이 지시문은 설명된 기능 또는 그 일부가 라이브러리나 C API에 추가된 Python 버전을 문서화합니다. 이 지시자가 모듈 전체에 적용될 때는 모듈 섹션의 맨 위, 어떤 설명문보다도 앞에 배치해야 합니다. 지시자를 사용하여 새 API(class, attribute, function, method, c:type 등)를 추가할 때는 설명 블록의 끝에 versionadded를 포함해야 합니다.

첫 번째 인자는 반드시 주어야 하며 해당 버전을 나타냅니다. 특정 버전 번호 대신 API가 다가오는 릴리스에서 처음 등장함을 나타내는 next라는 단어를 사용할 수 있으며, 또 그렇게 해야 합니다. 두 번째 인자는 선택 사항이며 기능의 세부 사항을 설명하는 데 사용할 수 있습니다.

예:

.. function:: func()

   Return foo and bar.

   .. versionadded:: next

릴리스가 이루어지면 릴리스 관리자가 next를 방금 릴리스된 버전으로 변경합니다. 예를 들어 위 예의 func가 3.14에서 릴리스되면 코드 조각은 다음과 같이 변경됩니다:

.. function:: func()

   Return foo and bar.

   .. versionadded:: 3.14

이 치환을 수행하는 도구는 릴리스 도구(release-tools) 저장소에 있는 update_version_next.py입니다.

과거 버전에 존재했지만 아직 문서화되지 않은 함수에 대한 문서를 추가할 때는 next 대신 해당 함수가 추가된 버전 번호를 사용하십시오.

versionchanged

versionadded와 비슷하지만, 지정한 기능이 언제 어떻게 변경되었는지(새 매개변수, 변경된 부작용, 플랫폼 지원 등)를 설명합니다. 이 지시자에는 두 번째 인자(변경 사항에 대한 설명)가 반드시 있어야 합니다.

예:

.. function:: func(spam=False)

   Return foo and bar, optionally with *spam* applied.

   .. versionchanged:: next
      Added the *spam* parameter.

지시문 헤드와 설명 사이에는 빈 줄이 없어야 한다는 점에 유의하십시오. 이는 마크업에서 이 블록들이 시각적으로 이어지도록 하기 위함입니다.

deprecated

설명된 기능이 폐지 예정이 된 버전을 나타냅니다.

필수 인자는 하나이며, 기능이 폐지 예정이 된 버전입니다. versionadded와 마찬가지로, API가 다음 릴리스에서 처음으로 폐지 예정이 됨을 나타내려면 next라는 단어를 사용해야 합니다.

예:

.. deprecated:: next

deprecated-removed

deprecated와 비슷하지만, 기능이 어느 버전에서 제거되는지도 나타냅니다.

필수 인자는 두 개이며, 기능이 폐지 예정이 된 버전(보통 next)과 기능이 제거되는 버전입니다. 제거되는 버전은 구체적인 버전 번호여야 합니다(next는 안 됩니다).

예:

.. deprecated-removed:: next 4.0

soft-deprecated

설명된 기능이 soft deprecated 상태가 된 버전을 나타냅니다.

필수 인자는 하나이며, 기능이 소프트 폐지 예정이 된 버전입니다. API가 다음 릴리스에서 처음으로 소프트 폐지 예정이 됨을 나타내려면 next라는 단어를 사용하십시오.

예:

.. soft-deprecated:: next

impl-detail

이 지시문은 CPython 고유의 정보를 표시하는 데 사용됩니다. 블록 내용과 함께 사용하거나 한 문장을 인자로 사용하십시오. 즉, 다음과 같이 하거나

.. impl-detail::

   This describes some implementation detail.

   More explanation.

또는

.. impl-detail:: This shortly mentions an implementation detail.

내용 앞에 “CPython 구현 상세:“가 자동으로 붙습니다.

seealso

많은 섹션에는 모듈 설명서나 외부 문서에 대한 참조 목록이 포함되어 있습니다. 이 목록은 seealso 지시문을 사용해 만듭니다.

seealso 지시문은 보통 섹션 안에서 하위 섹션들 바로 앞에 배치합니다. HTML 출력에서는 본문의 흐름과 분리된 상자 안에 표시됩니다.

seealso 지시문의 내용은 reST 정의 목록이어야 합니다. 예:

.. seealso::

   Module :mod:`zipfile`
      Documentation of the :mod:`zipfile` standard module.

   `GNU tar manual, Basic Tar Format <http://link>`_
      Documentation for tar archive files, including GNU tar extensions.

rubric

이 지시문은 목차 노드를 만드는 데 사용되지 않는 문단 제목을 만듭니다. 현재는 “각주” 캡션에 사용됩니다.

centered

이 지시문은 가운데 정렬된 굵은 글씨 문단을 만듭니다. 다음과 같이 사용하십시오:

.. centered::

   Paragraph contents.

목차 마크업

reST에는 여러 문서를 서로 연결하거나 문서를 여러 출력 파일로 나누는 기능이 없으므로, Sphinx는 사용자 정의 지시문을 사용해 문서를 구성하는 개별 파일 간의 관계와 목차를 추가합니다. toctree 지시문이 그 중심 요소입니다.

toctree

이 지시문은 지시문 본문에 지정된 파일들의 개별 목차(“하위 TOC 트리” 포함)를 사용해 현재 위치에 “TOC 트리”를 삽입합니다. 숫자로 된 maxdepth 옵션을 지정하여 트리의 깊이를 나타낼 수 있으며, 기본적으로는 모든 수준이 포함됩니다.

다음 예(라이브러리 레퍼런스 색인에서 가져왔습니다)를 살펴보십시오:

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   (many more files listed here)

이것은 두 가지 일을 합니다:

• 그 모든 파일의 목차가 최대 깊이 2, 즉 중첩된 제목 하나까지 삽입됩니다. 해당 파일들 안의 toctree 지시문도 함께 고려됩니다.

• Sphinx는 intro, strings 등의 파일 간 상대적 순서를 알고 있으며, 이 파일들이 표시된 파일인 라이브러리 색인의 자식이라는 것도 알고 있습니다. 이 정보로부터 “다음 장”, “이전 장”, “상위 장” 링크를 생성합니다.

결국 빌드 과정에 포함되는 모든 파일은 하나의 toctree 지시문에 나타나야 합니다. 포함되지 않은 파일은 표준 탐색으로 도달할 수 없다는 뜻이므로, Sphinx는 그런 파일을 발견하면 경고를 내보냅니다.

소스 디렉터리 루트에 있는 특수 파일 contents.rst는 TOC 트리 계층의 “루트”이며, 이 파일로부터 “목차” 페이지가 생성됩니다.

색인 생성 마크업

Sphinx는 앞서 설명한 것처럼 모든 정보 단위(함수, 클래스, 어트리뷰트 등)로부터 색인 항목을 자동으로 생성합니다.

하지만 색인을 더 포괄적으로 만들고, 언어 레퍼런스처럼 정보가 주로 정보 단위에 담겨 있지 않은 문서에서도 색인 항목을 사용할 수 있도록 명시적인 지시문도 제공됩니다.

이 지시문은 index이며 하나 이상의 색인 항목을 포함합니다. 각 항목은 콜론으로 구분된 유형과 값으로 구성됩니다.

예를 들면 다음과 같습니다:

.. index::
   single: execution; context
   module: __main__
   module: sys
   triple: module; search; path

이 지시문에는 다섯 개의 항목이 들어 있으며, 이 항목들은 생성된 색인의 항목으로 변환되어 index 문의 정확한 위치(오프라인 매체의 경우 해당 페이지 번호)로 연결됩니다.

가능한 항목 유형은 다음과 같습니다:

single

단일 색인 항목을 생성합니다. 하위 항목 텍스트를 세미콜론으로 구분하여 하위 항목으로 만들 수 있습니다(이 표기법은 아래에서 어떤 항목이 생성되는지 설명할 때도 사용됩니다).

pair

pair: loop; statement은 두 개의 색인 항목, 즉 loop; statement과 statement; loop를 생성하는 단축 표기입니다.

triple

마찬가지로 triple: module; search; path는 세 개의 색인 항목, 즉 module; search path, search; path, module, path; module search를 생성하는 단축 표기입니다.

모듈, 키워드, 연산자, 객체, 예외, 문장, 내장

이들은 모두 두 개의 색인 항목을 생성합니다. 예를 들어 module: hashlib은 module; hashlib과 hashlib; module 항목을 생성합니다. builtin 항목 유형은 두 항목을 만들 때 “builtin” 대신 “built-in function”(내장 함수)을 사용한다는 점에서 약간 다릅니다.

“single” 항목만 포함하는 색인 지시문에는 다음과 같은 축약 표기법이 있습니다.:

.. index:: BNF, grammar, syntax, notation

이것은 네 개의 색인 항목을 생성합니다.

문법 생성 규칙 표시

형식 문법의 생성 규칙을 표시하기 위한 특수 마크업을 사용할 수 있습니다. 이 마크업은 단순하며 BNF(또는 그 파생 형식)의 모든 측면을 모델링하려 하지는 않지만, 문맥 자유 문법을 표시할 때 기호가 사용된 곳이 해당 기호의 정의로 연결되는 하이퍼링크로 렌더링되도록 하기에는 충분한 기능을 제공합니다. 다음과 같은 지시문이 있습니다:

productionlist

이 지시문은 생성 규칙 그룹을 감싸는 데 사용됩니다. 각 생성 규칙은 한 줄에 작성하며, 이름과 그 뒤에 콜론으로 구분된 정의로 구성됩니다. 정의가 여러 줄에 걸치는 경우, 각 연속 줄은 첫 줄과 같은 열에 놓인 콜론으로 시작해야 합니다.

productionlist 지시문 인자 안에는 빈 줄을 사용할 수 없습니다.

정의에는 해석 텍스트로 표시된 토큰 이름을 포함할 수 있으며(예: unaryneg ::= "-" `integer`), 이렇게 하면 해당 토큰의 생성 규칙에 대한 상호 참조가 생성됩니다.

생성 규칙 안에서는 추가적인 reST 구문 분석이 이루어지지 않으므로 * 또는 | 문자를 이스케이프할 필요가 없다는 점에 유의하십시오.

다음은 Python 레퍼런스 매뉴얼에서 가져온 예입니다:

.. productionlist::
   try_stmt: try1_stmt | try2_stmt
   try1_stmt: "try" ":" `suite`
            : ("except" [`expression` ["," `target`]] ":" `suite`)+
            : ["else" ":" `suite`]
            : ["finally" ":" `suite`]
   try2_stmt: "try" ":" `suite`
            : "finally" ":" `suite`

치환

문서 시스템은 기본으로 정의된 세 가지 치환을 제공합니다. 이 치환들은 빌드 구성 파일 conf.py에서 설정합니다.

|release|

문서가 다루는 Python 릴리스로 치환됩니다. 이것은 알파/베타/릴리스 후보 태그를 포함한 전체 버전 문자열입니다. 예를 들면 2.5.2b3입니다.

|version|

문서가 다루는 Python 버전으로 치환됩니다. 버전 2.5.1에서도 예를 들어 2.5처럼 메이저 및 마이너 버전 부분만으로 구성됩니다.

|today|

오늘 날짜 또는 빌드 구성 파일에 설정된 날짜로 치환됩니다. 보통 April 14, 2007 형식을 따릅니다.