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의 자동 채우기 모드에 도움이 되도록 관례적으로 두 번째 공백을 넣습니다.

문단

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

인라인 마크업

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

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

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

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

연속된 텍스트에 별표나 역따옴표가 나타나 인라인 마크업 구분자와 혼동될 수 있다면 백슬래시로 이스케이프해야 합니다.

이 마크업에는 다음과 같은 몇 가지 제한이 있으므로 유의하십시오:

• 중첩할 수 없습니다,

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

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

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

reST는 사용자 정의 “해석된 텍스트 역할”도 허용하며, 이는 그 안의 텍스트를 특정 방식으로 해석해야 함을 나타냅니다. 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.

:: 표시의 처리는 영리합니다:

• 이 표시가 독립된 문단으로 나타나면 해당 문단은 문서에서 완전히 제외됩니다.

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

• 앞에 공백이 아닌 문자가 있으면 표시가 콜론 하나로 대체됩니다.

따라서 위 예제의 첫 번째 문단에 있는 두 번째 문장은 “다음 문단은 코드 예제입니다:”로 렌더링됩니다.

하이퍼링크

외부 링크

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

내부 링크

내부 링크는 특별한 reST 역할을 통해 만들며, 특정 마크업에 관한 절인 상호 참조 마크업을 참조하십시오.

절

절 제목은 텍스트 길이 이상의 문장 부호 문자로 제목 아래에 밑줄을 긋고 선택적으로 위에도 줄을 그어 만듭니다:

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

일반적으로 구조는 제목의 연속된 순서에 따라 결정되므로 특정 문자에 제목 수준이 할당되지 않습니다. 그러나 Python 문서에는 다음 규칙을 권장합니다:

• 부에는 윗줄이 있는 #

• 장에는 윗줄이 있는 *

• 절에는 =

• 하위 절에는 -

• 하위하위 절에는 ^

• 문단에는 "

명시적 마크업

“명시적 마크업”은 각주, 특별히 강조된 문단, 주석, 범용 지시자처럼 특별한 처리가 필요한 대부분의 구문에 reST에서 사용됩니다.

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

지시자

지시자는 명시적 마크업의 범용 블록입니다. 역할과 더불어 reST의 확장 메커니즘 중 하나이며, Sphinx에서 널리 사용됩니다.

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

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

   Return a line of text input from the user.

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

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

각주

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

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'입니다.

• 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 같은 운영 체제 수준 명령의 이름입니다.

dfn

텍스트에서 용어가 정의되는 부분을 표시하십시오. (색인 항목은 생성되지 않습니다.)

file

파일이나 디렉터리의 이름입니다. 콘텐츠 안에서는 예를 들어 중괄호를 사용하여 “variable” 부분을 나타낼 수 있습니다.:

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

Usenet 뉴스그룹의 이름입니다.

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

인터넷 의견 요청서(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 부분을 사용할 때 사용자가 알아야 하는 특히 중요한 정보입니다. 지시어의 내용은 완전한 문장으로 작성하고 적절한 문장 부호를 모두 포함해야 합니다.

예:

.. note::

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

warning

해당 경고와 관련된 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

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

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

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   (many more files listed here)

이는 다음 두 가지 작업을 수행합니다.

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

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

결국 빌드 프로세스에 포함된 모든 파일은 하나의 toctree 지시어에 나타나야 합니다. Sphinx는 포함되지 않은 파일을 발견하면 경고를 표시하는데, 이는 해당 파일에 표준 탐색을 통해 접근할 수 없다는 의미이기 때문입니다.

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

색인을 생성하는 마크업

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

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

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

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

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

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

사용할 수 있는 항목 형식은 다음과 같습니다.

single

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

pair

pair: loop; statement은 loop; statement 및 statement; loop이라는 두 색인 항목을 생성하는 약식 표기입니다.

triple

마찬가지로 triple: module; search; path는 module; search path, search; path, module 및 path; module search이라는 세 색인 항목을 생성하는 약식 표기입니다.

module, keyword, operator, object, exception, statement, builtin

이들은 모두 두 개의 색인 항목을 생성합니다. 예를 들어 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 형식입니다.