[Active] PEP 287 - reStructuredText Docstring Format

September 26, 2025

원문 링크: PEP 287 - reStructuredText Docstring Format

상태: Active 유형: Informational 작성일: 25-Mar-2002

PEP 287 – reStructuredText Docstring Format

개요 (Abstract)

이 PEP는 Python docstring, PEPs 및 관련 문서에서 구조화된 일반 텍스트 문서를 위한 표준 마크업 형식으로 reStructuredText 마크업을 채택할 것을 제안합니다. reStructuredText는 풍부하고 확장 가능하면서도 읽기 쉬운 WYSIWYG(What-You-See-Is-What-You-Get) 일반 텍스트 마크업 문법입니다.

이 PEP는 docstring의 저수준(low-level) 문법만을 다루며, docstring의 의미론(semantics)이나 처리에 대해서는 다루지 않습니다 (관련 내용은 PEP 256을 참조하십시오). 순수 일반 텍스트(plaintext) docstring의 사용을 비난하려는 시도가 아니며, 이는 항상 유효합니다. reStructuredText 마크업은 더 표현력 있는 docstring을 원하는 개발자들을 위한 대안입니다.

장점 (Benefits)

개발자는 본질적으로 게으른 종족입니다. 우리는 함수, 클래스, 모듈 및 서브시스템을 통해 코드를 재사용합니다. Python은 docstring 문법을 통해 코드 내부에서 문서를 작성할 수 있도록 합니다. Python Documentation Special Interest Group (Doc-SIG)의 “성배(holy grail)”는 Python 시스템의 docstring이 컨텍스트 내에서 추출되어 여러 목적에 유용한 고품질 문서로 처리될 수 있도록 하는 마크업 문법 및 도구 세트였습니다.

문서 마크업 언어에는 세 가지 고객 그룹이 있습니다: 문서를 작성하는 저자, 데이터를 처리하는 소프트웨어 시스템, 그리고 최종 소비자이자 가장 중요한 그룹인 독자입니다. 대부분의 마크업은 저자와 소프트웨어 시스템을 위해 설계되었으며, 독자는 처리된 형태(종이나 브라우저를 통해)만을 보게 됩니다. reStructuredText는 다릅니다: 마크업에 대한 사전 지식 없이도 소스 형태로 쉽게 읽을 수 있도록 의도되었습니다. reStructuredText는 일반 텍스트 형식으로 완전히 읽을 수 있으며, 많은 마크업 형태가 일반적인 사용법과 일치하므로(예: *강조), 매우 자연스럽게 읽힙니다. 그러면서도 복잡한 문서를 생성하기에 충분히 풍부하고, 확장 가능하여 거의 제한이 없습니다. 물론 reStructuredText 문서를 작성하려면 약간의 사전 지식이 필요합니다.

이 마크업은 소스 텍스트에서 쉬운 가독성을 유지하면서 기능성과 표현력을 제공합니다. 처리된 형태(HTML 등)는 독자들에게 모든 것을 접근 가능하게 만듭니다: 인라인 라이브 하이퍼링크, 각주로의 라이브 링크 및 각주로부터의 링크, 자동 목차(라이브 링크 포함!), 테이블, 다이어그램 등을 위한 이미지, 쾌적하고 읽기 쉬운 스타일이 적용된 텍스트.

reStructuredText 파서는 현재 Docutils 프로젝트의 일부로 사용할 수 있습니다. 독립 실행형 reStructuredText 문서와 PEP는 HTML로 변환할 수 있으며, 다른 출력 형식 라이터(writer)는 개발 중이며 시간이 지남에 따라 제공될 것입니다. docstring에서 자동 문서를 구현할 Python 소스 “Reader”에 대한 작업이 진행 중입니다. 기존 자동 문서화 도구의 저자들은 reStructuredText 파서를 프로젝트에 통합하거나, 더 나아가 Python 표준 라이브러리를 위한 세계적 수준의 도구 세트를 만들기 위해 협력할 것을 권장합니다.

가까운 미래에 개발자들이 기존 docstring에서 온라인 도움말을 위한 HTML, 여러 목적을 위한 XML, 그리고 궁극적으로 인쇄 문서를 위한 PDF, DocBook, LaTeX를 “거의 무료로” 생성할 수 있도록 하는 도구들이 제공될 것입니다. 표준의 채택은 적어도 docstring 처리 도구들이 더 이상의 “바퀴의 재발명(reinventing the wheel)”을 막음으로써 이점을 얻게 할 것입니다.

궁극적으로 유일한 기존 표준 자동 문서화 도구인 PyDoc은 reStructuredText 지원을 추가할 수 있을 것입니다. 그동안은 모든 docstring을 미리 포맷된 일반 텍스트로 처리하기 때문에 reStructuredText 마크업에 문제가 없을 것입니다.

목표 (Goals)

Doc-SIG에서 논의된 바와 같이, docstring 형식에 대한 일반적으로 받아들여지는 목표는 다음과 같습니다:

일반 사용자가 소스 형태로 읽을 수 있어야 합니다.
어떤 표준 텍스트 편집기로도 쉽게 입력할 수 있어야 합니다.
모듈 파싱을 통해 추론할 수 있는 정보를 포함할 필요가 없어야 합니다.
합리적인 마크업 형식으로 변환될 수 있도록 충분한 정보(구조)를 포함해야 합니다.
마크업 언어에 방해받는다는 느낌 없이 모듈의 전체 문서를 docstring에 작성할 수 있어야 합니다.

reStructuredText는 이 모든 목표를 충족하고 능가하며, 더욱 엄격한 자체 목표를 설정합니다. 자세한 내용은 아래 “Docstring-Significant Features”를 참조하십시오.

이 PEP의 목표는 다음과 같습니다:

docstring (Python 모듈 및 패키지의 인라인 문서), PEPs, README-유형 파일 및 기타 독립 실행형 문서를 위한 표준 구조화된 일반 텍스트 형식으로 reStructuredText를 확립하는 것입니다. “승인됨(Accepted)” 상태는 Python 커뮤니티의 합의와 궁극적인 BDFL(Benevolent Dictator For Life) 선언을 통해 추구될 것입니다.
- reStructuredText는 표준으로 제안되지만, 유일한 표준은 아닙니다. 그 사용은 전적으로 선택 사항입니다. 사용하고 싶지 않은 사람은 사용할 필요가 없습니다.
Python 커뮤니티에서 제기된 관련 우려 사항을 요청하고 해결하는 것입니다.
커뮤니티 지원을 장려하는 것입니다. 여러 경쟁 마크업이 존재하는 한 개발 커뮤니티는 분열되어 있습니다. 일단 표준이 존재하면 사람들은 그것을 사용하기 시작할 것이고, 추진력은 필연적으로 모일 것입니다.
관련 자동 문서화 프로젝트의 노력을 통합하는 것입니다. 관심 있는 개발자들이 힘을 합쳐 공동/병합/공통 구현을 작업하기를 희망합니다.

reStructuredText가 Python 표준이 되면, 표준에 대해 논쟁하는 대신 도구에 노력을 집중할 수 있습니다. Python은 표준화된 문서 도구 세트가 필요합니다.

PEPs와 관련하여 다음 전략 중 하나 또는 둘 다 적용될 수 있습니다:

기존 PEP 섹션 구조 구성(한 줄 섹션 헤더, 들여쓰기된 본문 텍스트)을 유지합니다. 하위 섹션은 금지되거나, 들여쓰기된 본문 텍스트에 reStructuredText 스타일의 밑줄 헤더로 지원될 수 있습니다.
PEP 섹션 구조 구성을 reStructuredText 문법으로 대체합니다. 섹션 헤더는 밑줄을 필요로 하며, 하위 섹션은 즉시 지원되고, 본문 텍스트는 들여쓰기할 필요가 없습니다 (블록 인용문 제외).

전략 (b)가 권장되며, 그 구현은 완료되었습니다.

RFC 2822 헤더 지원은 PEPs를 위한 reStructuredText 파서에 추가되었습니다 (특정 컨텍스트, 즉 문서의 첫 번째 연속 블록이 주어졌을 때 명확함). 균일성을 위해 PEP 섹션 헤더에 허용되는 오버라인/밑줄 스타일을 구체적으로 지정하는 것이 바람직할 수 있습니다.

배경 (Rationale)

docstring에 대한 표준 문법의 부재는 docstring을 표준 형식(예: HTML, DocBook, TeX)의 문서로 추출하고 변환하는 표준 도구의 개발을 방해했습니다. 여러 제안된 마크업 형식과 변형, 그리고 이러한 제안에 묶인 많은 도구들이 있었지만, 표준 docstring 형식이 없으면 강력한 지지를 얻지 못했거나 미완성으로 좌초되었습니다.

Doc-SIG의 존재 내내 단일 표준 docstring 형식에 대한 합의는 결코 이루어지지 않았습니다. 다음을 포함한 여러 이유로 경량의 암묵적 마크업이 추구되었습니다:

Python 코드 내에 작성된 docstring은 대화형 인터프리터 내에서 사용할 수 있으며 “print”할 수 있습니다. 따라서 쉬운 가독성을 위해 일반 텍스트를 사용합니다.
개발자들은 원본 docstring의 가독성을 희생하지 않고 docstring에 구조를 추가하기를 원합니다.
꾸밈 없는 일반 텍스트는 유용한 구조화된 형식으로 변환(“up-translated”)될 수 없습니다.
명시적 마크업(XML 또는 TeX와 같은)은 익숙하지 않은 사람들에게는 일반적으로 읽기 어렵다고 간주됩니다.
암묵적 마크업은 깔끔하고 미니멀리스트적인 Python 문법과 미학적으로 호환됩니다.

수년 동안 Doc-SIG에서 docstring을 위한 많은 대체 마크업이 제안되었습니다. 대표적인 예시가 아래에 나열되어 있습니다. 각 마크업은 위에 언급된 목표의 관점에서 간략하게 분석됩니다. 이것이 모든 기존 마크업 시스템의 배타적인 목록이 아니라는 점에 유의하십시오. (Texinfo, Doxygen, TIM, YODL, AFT 등) 언급되지 않은 많은 다른 마크업이 있습니다.

XML, SGML, DocBook, HTML, XHTML: XML 및 SGML은 모든 종류의 문서에 적합한 명시적이고 잘 정돈된 메타 언어입니다. XML은 SGML의 변형입니다. 이들은 훈련받지 않은 눈에는 장황하고, 입력하기 어려우며, 소스로서 편안하게 읽기에는 너무 복잡하기 때문에 주로 배후에서 사용됩니다. DocBook, HTML, XHTML은 모두 SGML 및/또는 XML의 응용 프로그램이며, 동일한 기본 문법과 동일한 단점을 공유합니다.
TeX: TeX는 XML/SGML과 유사하게 명시적이지만, 작성하기 쉽지 않고, 익숙하지 않은 사람들에게는 읽기 어렵습니다.
Perl POD: 대부분의 Perl 모듈은 POD(Plain Old Documentation)라는 형식으로 문서화됩니다. 이는 Perl 파서와 강력하게 통합된, 입력하기 쉽고 매우 낮은 수준의 형식입니다. POD 문서를 info, HTML, man 페이지 등 다른 형식으로 변환하는 많은 도구들이 존재합니다. 그러나 POD 문법은 가독성 면에서 Perl 자체를 따릅니다.
JavaDoc: Java 클래스 및 함수 앞의 특별한 주석이 코드 문서를 작성하는 데 사용됩니다. 이를 추출하여 HTML 문서로 변환하는 프로그램은 javadoc이라고 불리며, 표준 Java 배포판의 일부입니다. 그러나 JavaDoc은 대부분의 마크업에 HTML 태그를 사용하여 HTML과 매우 밀접한 관계를 가지고 있습니다. 따라서 HTML의 가독성 문제를 공유합니다.
Setext, StructuredText: 초기에 Setext(Structure Enhanced Text)의 변형들, Zope Corp의 StructuredText를 포함하여, Python docstring 형식 지정을 위해 제안되었습니다. 이후 이러한 변형들을 통칭하여 “STexts”라고 부를 것입니다. STexts는 특별한 지식 없이도 읽기 쉽고, 비교적 작성하기 쉽다는 장점이 있습니다.

일부 사용자(대부분의 기존 Python 자동 문서화 도구 포함)에 의해 사용되었음에도 불구하고, 지금까지 STexts는 다음과 같은 이유로 표준이 되지 못했습니다:

STexts는 불완전했습니다. 사람들이 docstring에서 사용하고 싶어하는 “필수적인” 구성이 부족하여 STexts는 이상적이지 못했습니다. 이러한 “필수적인” 구성은 보편적이지 않으며, 모든 사람이 자신의 요구 사항을 가지고 있다는 점에 유의하십시오.
STexts는 때때로 예상치 못했습니다. 텍스트 조각이 예상치 못하게 마크업된 것으로 해석되어 사용자에게 불만을 초래했습니다.
SText 구현은 버그가 많았습니다. 대부분의 STexts는 구현 자체를 제외하고는 공식적인 사양이 없었습니다. 버그 있는 구현은 버그 있는 사양을 의미했으며, 그 반대도 마찬가지였습니다.
마크업 문자가 비-마크업 컨텍스트에서 사용될 때 SText 마크업 규칙을 우회할 메커니즘이 없었습니다. 다시 말해, 마크업을 이스케이프할 방법이 없었습니다.

암묵적 STexts의 지지자들은 명시적 마크업(XML, HTML, TeX, POD 등)에 대한 제안에 강력하게 반대했으며, 이 논쟁은 1996년 또는 그 이전부터 계속되었습니다.

reStructuredText는 위에 나열된 모든 문제를 해결하면서 SText 아이디어를 완전히 수정하고 재해석한 것입니다.

명세 (Specification)

reStructuredText의 명세와 사용자 문서는 매우 광범위합니다. 여기에서 모든 것을 반복하거나 요약하는 대신, 원본 문서에 대한 링크가 제공됩니다.

먼저 짧고 쉬운 입문서인 A ReStructuredText Primer를 살펴보십시오. Quick reStructuredText user reference는 모든 마크업 구성을 빠르게 요약합니다. 완전하고 광범위한 세부 정보는 다음 문서를 참조하십시오:

또한, Problems With StructuredText는 StructuredText와 관련하여 이루어진 많은 마크업 결정 사항을 설명하고, A Record of reStructuredText Syntax Alternatives는 독립적으로 이루어진 마크업 결정 사항을 기록합니다.

Docstring 관련 주요 기능 (Docstring-Significant Features)

마크업 이스케이프 메커니즘 (Markup escaping mechanism)

백슬래시(\)는 마크업 문자가 비-마크업 목적으로 필요할 때 이스케이프하는 데 사용됩니다. 그러나 인라인 마크업 인식 규칙은 백슬래시 이스케이프가 필요한 경우를 최소화하도록 구성되었습니다. 예를 들어, 별표는 강조를 위해 사용되지만, "*" 또는 "(*)" 또는 "x * y"와 같은 비-마크업 컨텍스트에서는 별표가 마크업으로 해석되지 않고 그대로 유지됩니다. 백슬래시의 많은 비-마크업 사용(예: 정규 표현식 설명)의 경우, 인라인 리터럴 또는 리터럴 블록이 적용됩니다; 다음 항목을 참조하십시오.

Python 소스 코드 및 Python 대화형 세션 포함 마크업: 인라인 리터럴, 리터럴 블록, doctest 블록 (Markup to include Python source code and Python interactive sessions: inline literals, literal blocks, and doctest blocks)

인라인 리터럴(Inline literals): 프로그램 I/O 또는 코드 스니펫을 나타내기 위해 이중 백쿼트()를 사용합니다. 인라인 리터럴 내에서는 마크업 해석(백슬래시 이스케이프[ \ ] 해석 포함)이 수행되지 않습니다.
리터럴 블록(Literal blocks): 코드 발췌문 또는 ASCII 그래픽과 같은 블록 수준의 리터럴 텍스트는 들여쓰기되며, 이전 단락 끝에 이중 콜론(::)으로 표시됩니다.
```
if literal_block:
    text = 'is left as-is'
    spaces_and_linebreaks = 'are preserved'
    markup_processing = None
```

doctest 블록(Doctest blocks): >>> 로 시작하고 빈 줄로 끝납니다. 들여쓰기나 리터럴 블록의 이중 콜론은 필요하지 않습니다. 예를 들면 다음과 같습니다:

Here's a doctest block:
>>> print 'Python-specific usage examples; begun with ">>>"'
Python-specific usage examples; begun with ">>>"
>>> print '(cut and pasted from interactive sessions)'
(cut and pasted from interactive sessions)

Python 식별자를 분리하는 마크업: 해석된 텍스트 (Markup that isolates a Python identifier: interpreted text)

단일 백쿼트(`)로 묶인 텍스트는 “해석된 텍스트(interpreted text)”로 인식되며, 그 해석은 애플리케이션에 따라 다릅니다. Python docstring의 컨텍스트에서 해석된 텍스트의 기본 해석은 Python 식별자입니다. 텍스트는 주어진 식별자에 대한 문서에 연결된 하이퍼링크로 마크업됩니다. 조회 규칙은 Python 자체와 동일합니다: LGB 네임스페이스 조회(local, global, builtin). 해석된 텍스트의 “역할(role)”(클래스, 모듈, 함수 등을 식별하는)은 네임스페이스 조회를 통해 암묵적으로 결정됩니다. 예를 들면 다음과 같습니다:

class Keeper(Storer):
    """
    Keep data fresher longer. Extend `Storer`.
    Class attribute `instances` keeps track of the number of `Keeper` objects instantiated.
    """
    instances = 0
    """How many `Keeper` objects are there?"""
    def __init__(self):
        """
        Extend `Storer.__init__()` to keep track of instances.
        Keep count in `self.instances` and data in `self.data`.
        """
        Storer.__init__(self)
        self.instances += 1
        self.data = []
        """Store data in a list, most recent last."""
    def storedata(self, data):
        """
        Extend `Storer.storedata()`; append new `data` to a list (in `self.data`).
        """
        self.data = data

각 해석된 텍스트 조각은 해당 docstring을 포함하는 블록의 로컬 네임스페이스에 따라 조회됩니다.

Python 식별자를 분리하고 그 유형을 지정하는 마크업: 역할이 있는 해석된 텍스트 (Markup that isolates a Python identifier and specifies its type: interpreted text with roles)

Python 소스 컨텍스트 리더는 명시적 역할이 필요하지 않도록 설계되었지만, 역할을 사용할 수 있습니다. 식별자를 명시적으로 분류하기 위해 역할은 접두사 또는 접미사 형식으로 식별자와 함께 제공됩니다.

Use :method:Keeper.storedata to store the object's data in Keeper.data:instance_attribute:.

역할에 대해 선택된 문법은 장황하지만, 필연적으로 그렇습니다 (더 나은 대안이 있다면 Doc-SIG에 게시해 주십시오). 마크업의 의도는 명시적 역할을 사용할 필요가 거의 없어야 한다는 것입니다. 그 사용은 절대적인 최소한으로 유지되어야 합니다.

“태그 목록” 또는 “레이블 목록”을 위한 마크업: 필드 목록 (Markup for “tagged lists” or “label lists”: field lists)

필드 목록(Field lists)은 필드 이름에서 필드 본문으로의 매핑을 나타냅니다. 이는 주로 “서지 필드 목록”(저자, 날짜, 버전과 같은 문서 메타데이터를 나타냄) 및 지시문(directives)의 확장 속성(아래 참조)과 같은 확장 문법에 사용됩니다. 매개변수 식별, 발생 예외 등과 같은 방법론(docstring 의미론)을 구현하는 데 사용될 수 있습니다. 이러한 사용은 이 PEP의 범위를 벗어납니다.

수정된 RFC 2822 문법이 사용되며, 필드 이름 앞뒤에 콜론이 있습니다. 필드 본문도 더 다양합니다; 여러 필드 본문(심지어 중첩된 필드 목록)을 포함할 수 있습니다. 예를 들면 다음과 같습니다:

:Date: 2002-03-22
:Version: 1
:Authors: - Me
          - Myself
          - I

표준 RFC 2822 헤더 문법은 모호하기 때문에 이 구성을 위해 사용될 수 없습니다. 한 줄 시작 부분에 콜론이 뒤따르는 단어는 일반적인 서면 텍스트에서 흔합니다.

마크업 확장성: 지시문 및 대체 (Markup extensibility: directives and substitutions)

지시문(Directives)은 reStructuredText의 확장 메커니즘으로 사용되며, 새로운 문법을 추가하지 않고 새로운 블록 수준 구성을 지원하는 방법입니다. 이미지, 경고(note, caution 등), 목차 생성(다른 것들 중)을 위한 지시문이 구현되었습니다. 예를 들어, 이미지를 배치하는 방법은 다음과 같습니다:

.. image:: mylogo.png

대체 정의(Substitution definitions)는 인라인 텍스트로 블록 수준 지시문의 힘과 유연성을 공유할 수 있도록 합니다. 예를 들면 다음과 같습니다:

The |biohazard| symbol must be used on containers used to dispose of medical waste.
.. |biohazard| image:: biohazard.png

섹션 구조 마크업 (Section structure markup)

reStructuredText의 섹션 헤더는 들여쓰기가 아닌 밑줄(및 선택적으로 오버라인)을 통한 장식(adornment)을 사용합니다. 예를 들면 다음과 같습니다:

This is a Section Title
=======================

This is a Subsection Title
--------------------------
This paragraph is in the subsection.

This is Another Section Title
=============================
This paragraph is in the second section.

질문 및 답변 (Questions & Answers)

`reStructuredText`는 충분히 풍부한가요? (Is reStructuredText rich enough?)

네, 대부분의 사람들에게는 그렇습니다. 특정 애플리케이션에 필요한 구성이 부족하다면 지시문 메커니즘을 통해 추가할 수 있습니다. 유용하고 일반적인 구성이 간과되었고 적절하게 읽을 수 있는 문법을 찾을 수 있다면, 명세와 파서에 추가될 수 있습니다.

`reStructuredText`는 너무 풍부한가요? (Is reStructuredText too rich?)

특정 애플리케이션이나 개인에게는 그럴 수도 있습니다. 일반적으로는 그렇지 않습니다.

docstring 마크업 문법이 Doc-SIG에 제안될 때마다, 누군가는 어떤 구성에 대한 지원 부족에 대해 불평했습니다. 답변은 종종 “우리가 말하는 것은 docstring이고, docstring은 복잡한 마크업을 가질 필요가 없습니다”와 같았습니다. 문제는 한 사람에게는 불필요해 보이는 구성이 다른 사람에게는 절대적으로 필수적일 수 있다는 것입니다.

reStructuredText는 정반대의 접근 방식을 취합니다: 풍부한 암묵적 마크업 구성 세트(및 명시적 마크업을 위한 일반 확장 메커니즘)를 제공하여 모든 종류의 문서를 허용합니다. 구성 세트가 특정 애플리케이션에 너무 풍부하다면, 사용되지 않는 구성은 파서에서 제거(애플리케이션별 재정의를 통해)하거나 단순히 관례상 생략할 수 있습니다.

StructuredText처럼 섹션 구조에 들여쓰기를 사용하지 않는 이유는 무엇인가요? 더 “Pythonic”하지 않나요? (Why not use indentation for section structure, like StructuredText does? Isn’t it more “Pythonic”?)

Guido van Rossum은 2001년 6월 13일 Doc-SIG 게시물에 다음과 같이 썼습니다:

저는 여전히 섹션을 나타내기 위해 들여쓰기를 사용하는 것이 잘못되었다고 생각합니다. 실제 서적 및 기타 인쇄 출판물이 어떻게 배치되는지 살펴보면, 들여쓰기는 자주 사용되지만 주로 섹션 내 수준에서 사용된다는 것을 알 수 있습니다. 들여쓰기는 목록, 표, 인용문, 예제 등을 구분하는 데 사용될 수 있습니다. (docstring이 텍스트 포맷터의 입력이기 때문에 다르다는 주장은 잘못되었습니다: 핵심은 처리 없이도 읽을 수 있어야 한다는 것입니다).

저는 들여쓰기를 사용하는 것이 Pythonic하다는 주장을 거부합니다. 텍스트는 코드가 아니며, 다른 전통과 관습이 적용됩니다. 사람들은 30세기 이상 동안 가독성을 위해 텍스트를 제시해왔습니다. 불필요하게 혁신하지 맙시다.

자세한 내용은 Problems With StructuredText의 “Section Structure via Indentation”을 참조하십시오.

PEPs에 `reStructuredText`를 사용하는 이유는 무엇인가요? 기존 표준의 문제점은 무엇인가요? (Why use reStructuredText for PEPs? What’s wrong with the existing standard?)

PEPs에 대한 기존 표준은 일반적인 표현력 측면에서 매우 제한적이며, 특히 참조가 풍부한 문서 유형에 대한 참조 기능이 부족합니다. PEPs는 현재 HTML로 변환되지만, 결과물(대부분 모노스페이스 텍스트)은 매력적이지 않으며, HTML의 부가가치 잠재력(특히 인라인 하이퍼링크)은 대부분 활용되지 않습니다.

reStructuredText를 PEPs의 표준 마크업으로 만들면 섹션 구조, 인라인 마크업, 그래픽 및 테이블 지원을 포함하여 훨씬 더 풍부한 표현이 가능해집니다. 여러 PEPs에는 일반 텍스트 문서가 지원할 수 있는 모든 ASCII 그래픽 다이어그램이 있습니다. PEPs가 HTML 형태로 제공되므로, 적절한 다이어그램을 포함하는 기능은 즉시 유용할 것입니다.

현재 PEP 관행은 텍스트에 “[1]” 형식의 참조 마커를 허용하며, 각주/참조 자체는 문서 끝 부분의 섹션에 나열됩니다. 현재 참조 마커와 각주/참조 자체 사이에 하이퍼링크가 없습니다 (pep2html.py에 추가할 수 있지만, “마크업” 자체가 모호하여 실수가 불가피합니다). 많은 참조를 포함하는 PEP(이 PEP와 같은 ;-)는 앞뒤로 많이 넘겨봐야 합니다. PEP를 수정할 때 종종 새로운 참조가 추가되거나 사용되지 않는 참조가 삭제됩니다. 참조 번호를 다시 매기는 것은 두 곳에서 해야 하고 연쇄 효과를 가질 수 있으므로 고통스럽습니다 (새로운 참조 1을 하나 삽입하면 다른 모든 참조의 번호를 다시 매겨야 합니다; 항상 새로운 참조를 끝에 추가하는 것은 최적이 아닙니다). 참조가 동기화되지 않을 수 있습니다.

PEPs는 두 가지 목적으로 참조를 사용합니다: 간단한 URL 참조와 각주. reStructuredText는 이 둘을 구분합니다. PEP는 다음과 같은 참조를 포함할 수 있습니다:

Abstract
This PEP proposes adding frungible doodads to the core. It extends PEP 9876 via the BCA mechanism.
...
References and Footnotes
 http://www.example.org/
 PEP 9876, Let's Hope We Never Get Here
    http://peps.python.org/pep-9876/
 "Bogus Complexity Addition"

참조 1은 간단한 URL 참조입니다. 참조 2는 텍스트와 URL을 포함하는 각주입니다. 참조 3은 텍스트만 포함하는 각주입니다. reStructuredText를 사용하여 다시 작성하면 이 PEP는 다음과 같이 보일 수 있습니다:

Abstract
========
This PEP proposes adding `frungible doodads`_ to the core. It extends PEP 9876 [#pep9876]_ via the BCA [#]_ mechanism.
...
References & Footnotes
======================
.. _frungible doodads: http://www.example.org/
.. [#pep9876] PEP 9876, Let's Hope We Never Get Here
.. [#] "Bogus Complexity Addition"

URL과 각주는 원하는 경우 참조 가까이에 정의할 수 있어 소스 텍스트에서 읽기 쉬워지고 PEP를 수정하기 쉬워집니다. “References and Footnotes” 섹션은 문서 트리 변환(document tree transform)으로 자동 생성될 수 있습니다. PEP 전체의 각주는 표준 헤더 아래에 수집되어 표시됩니다. URL 참조도 명시적으로 작성되어야 하는 경우(인용 형식으로), 다른 트리 변환을 사용할 수 있습니다.

URL 참조는 이름 지정될 수 있으며(“frungible doodads”), 추가 정의 없이 문서의 여러 위치에서 참조될 수 있습니다. HTML로 변환될 때 참조는 인라인 하이퍼링크(HTML <a> 태그)로 대체됩니다. 두 각주는 자동으로 번호가 매겨지므로 항상 동기화 상태를 유지합니다. 첫 번째 각주에는 내부 참조 이름 “pep9876”도 포함되어 있어 소스 텍스트에서 참조와 각주 사이의 연결을 더 쉽게 볼 수 있습니다. 이름 지정된 각주는 여러 번 참조될 수 있으며, 일관된 번호 매기기를 유지합니다.

“#pep9876” 각주는 인용 형식으로도 작성될 수 있습니다:

It extends PEP 9876 [PEP9876]_ ... .. [PEP9876] PEP 9876, Let's Hope We Never Get Here

각주는 번호가 매겨지지만, 인용은 참조에 텍스트를 사용합니다.

docstring 및 PEP 제안을 분리하는 것이 더 낫지 않을까요? (Wouldn’t it be better to keep the docstring and PEP proposals separate?)

PEP 마크업 제안은 PEP 마크업의 필요성이 없다고 판단되면 제거될 수 있거나, 별도의 PEP로 만들어질 수 있습니다. 승인된다면, PEP 1, PEP Purpose and Guidelines, 및 PEP 9, Sample PEP Template가 업데이트될 것입니다.

Python에서 구조화된 일반 텍스트의 모든 용도에 대해 단일의 일관된 마크업 표준을 채택하고, 이를 한곳에서 제안하는 것이 자연스러워 보입니다.

기존 pep2html.py 스크립트는 기존 PEP 형식을 HTML로 변환합니다. 새 형식의 PEP는 어떻게 HTML로 변환될까요? (The existing pep2html.py script converts the existing PEP format to HTML. How will the new-format PEPs be converted to HTML?)

reStructuredText 파싱이 통합된 새 버전의 pep2html.py가 완성되었습니다. Docutils 프로젝트는 “PEP Reader” 구성 요소를 통해 PEPs를 지원하며, 현재 pep2html.py의 모든 기능(PEP 및 RFC 참조의 자동 인식, 이메일 마스킹 등)을 포함합니다.

누가 기존 PEPs를 `reStructuredText`로 변환할까요? (Who’s going to convert the existing PEPs to reStructuredText?)

PEP 저자 또는 자원봉사자는 원하는 경우 기존 PEPs를 변환할 수 있지만, 그렇게 할 의무는 없습니다. reStructuredText 기반 PEPs는 기존 PEP 표준과 공존할 것입니다. 6번 질문 답변에서 언급된 pep2html.py는 기존 및 새 표준을 모두 처리합니다.

README 및 기타 보조 파일에 `reStructuredText`를 사용하는 이유는 무엇인가요? (Why use reStructuredText for README and other ancillary files?)

위 4번 질문 답변에서 PEPs에 대해 제시된 이유는 README 및 기타 보조 파일에도 적용됩니다. 표준 마크업을 채택함으로써 이러한 파일은 매력적인 상호 참조 HTML로 변환되어 python.org에 게시될 수 있습니다. 다른 프로젝트 개발자들도 이 기능을 자신의 문서에 활용할 수 있습니다.

기존 마크업 규칙과의 피상적인 유사성이 문제를 일으키고, 사람들이 유효하지 않은 마크업을 작성(그리고 일반 텍스트가 자연스러워 보여서 눈치채지 못함)하게 만들지 않을까요? `reStructuredText`는 “완벽하지 않은” 마크업에 얼마나 관대한가요? (Won’t the superficial similarity to existing markup conventions cause problems, and result in people writing invalid markup (and not noticing, because the plaintext looks natural)? How forgiving is reStructuredText of “not quite right” markup?)

한 프로그래밍 언어에서 다른 프로그래밍 언어로 전환할 때와 마찬가지로 일부 실수가 있을 것입니다. 다른 언어와 마찬가지로 경험을 통해 숙련도가 향상됩니다. 다행히 reStructuredText는 매우 작은 언어입니다.

어떤 문법이든 문법 오류의 가능성은 있습니다. 사용자는 입력에 대해 처리 시스템을 실행하고 출력이 정확한지 확인할 것으로 예상됩니다.

엄격한 의미에서 reStructuredText 파서는 매우 관대하지 않습니다 (그래야 합니다; “모호함에 직면했을 때, 추측하려는 유혹을 거부하라”는 마크업 파싱뿐만 아니라 컴퓨터 언어에도 적용됩니다). An Introduction to reStructuredText의 설계 목표 3은 다음과 같습니다:

명확해야 합니다. 마크업 규칙은 해석의 여지를 두어서는 안 됩니다. 어떤 주어진 입력에 대해 단 하나의 가능한 출력(오류 출력 포함)만 있어야 합니다.

관대하지 않지만, 동시에 파서는 유용한 진단 출력(“시스템 메시지”)을 생성하여 도움을 주려고 노력합니다. 파서는 문제의 심각도 수준(가장 낮은 것부터 높은 것까지: debug, info, warning, error, severe)을 나타내어 보고합니다. 사용자 또는 클라이언트 소프트웨어는 보고 임계값을 결정할 수 있습니다; 저수준 문제는 무시하거나 고수준 문제가 즉시 처리를 중단시키도록 할 수 있습니다. 문제는 파싱 중에도 보고되며 출력에도 포함되는데, 종종 문제의 원본과 이를 설명하는 시스템 메시지 사이에 양방향 링크가 있습니다.

Python 표준 라이브러리 모듈의 docstring은 `reStructuredText`로 변환될까요? (Will the docstrings in the Python standard library modules be converted to reStructuredText?)

아니요. Python의 라이브러리 참조 문서는 소스와 별도로 관리됩니다. Python 표준 라이브러리의 docstring은 라이브러리 참조 문서를 복제하려고 시도해서는 안 됩니다. Python 표준 라이브러리의 docstring에 대한 현재 정책은 간결한 힌트, 간단하고 마크업이 없는 것이어야 한다는 것입니다 (비록 많은 경우 임시적인 암묵적 마크업을 포함하고 있지만).

모든 문자열을 유니코드로 작성하고 싶습니다. 문제가 생길까요? (I want to write all my strings in Unicode. Will anything break?)

파서는 유니코드를 완전히 지원합니다. Docutils는 임의의 입력 및 출력 인코딩을 지원합니다.

커뮤니티에 새로운 구조화된 텍스트 디자인이 필요한 이유는 무엇인가요? (Why does the community need a new structured text design?)

기존의 구조화된 텍스트 디자인은 위 “배경”에서 제시된 이유들로 인해 결함이 있습니다. reStructuredText는 “읽을 수 있는 일반 텍스트” 매체의 한계 내에서 완전한 마크업 문법이 되는 것을 목표로 합니다.

기존 문서화 방법론에 문제가 있나요? (What is wrong with existing documentation methodologies?)

어떤 기존 방법론을 말씀하시나요? Python docstring의 경우, JavaDoc과 같은 문서화 방법론은 고사하고 공식적인 표준 마크업 형식도 없습니다. 방법론 문제는 문법(이 PEP가 다루는)보다 훨씬 높은 수준의 문제입니다. 이는 잠재적으로 훨씬 더 논란의 여지가 있고 해결하기 어려우므로, 이 논의에서 의도적으로 제외되었습니다.

이 문서는 퍼블릭 도메인에 공개되었습니다.

감사의 말 (Acknowledgements)

일부 텍스트는 Moshe Zadka의 PEP 216, Docstring Format에서 차용되었습니다.

Python Doc-SIG의 모든 과거 및 현재 회원들에게 특별히 감사드립니다.

⚠️ 알림: 이 문서는 AI를 활용하여 번역되었으며, 기술적 정확성을 보장하지 않습니다. 정확한 내용은 반드시 원문을 확인하시기 바랍니다.

[Active] PEP 287 - reStructuredText Docstring Format

PEP 287 – reStructuredText Docstring Format

개요 (Abstract)

장점 (Benefits)

목표 (Goals)

배경 (Rationale)

명세 (Specification)

Docstring 관련 주요 기능 (Docstring-Significant Features)

마크업 이스케이프 메커니즘 (Markup escaping mechanism)

Python 소스 코드 및 Python 대화형 세션 포함 마크업: 인라인 리터럴, 리터럴 블록, doctest 블록 (Markup to include Python source code and Python interactive sessions: inline literals, literal blocks, and doctest blocks)

Python 식별자를 분리하는 마크업: 해석된 텍스트 (Markup that isolates a Python identifier: interpreted text)

Python 식별자를 분리하고 그 유형을 지정하는 마크업: 역할이 있는 해석된 텍스트 (Markup that isolates a Python identifier and specifies its type: interpreted text with roles)

“태그 목록” 또는 “레이블 목록”을 위한 마크업: 필드 목록 (Markup for “tagged lists” or “label lists”: field lists)

마크업 확장성: 지시문 및 대체 (Markup extensibility: directives and substitutions)

섹션 구조 마크업 (Section structure markup)

질문 및 답변 (Questions & Answers)

`reStructuredText`는 충분히 풍부한가요? (Is reStructuredText rich enough?)

`reStructuredText`는 너무 풍부한가요? (Is reStructuredText too rich?)

StructuredText처럼 섹션 구조에 들여쓰기를 사용하지 않는 이유는 무엇인가요? 더 “Pythonic”하지 않나요? (Why not use indentation for section structure, like StructuredText does? Isn’t it more “Pythonic”?)

PEPs에 `reStructuredText`를 사용하는 이유는 무엇인가요? 기존 표준의 문제점은 무엇인가요? (Why use reStructuredText for PEPs? What’s wrong with the existing standard?)

docstring 및 PEP 제안을 분리하는 것이 더 낫지 않을까요? (Wouldn’t it be better to keep the docstring and PEP proposals separate?)

기존 pep2html.py 스크립트는 기존 PEP 형식을 HTML로 변환합니다. 새 형식의 PEP는 어떻게 HTML로 변환될까요? (The existing pep2html.py script converts the existing PEP format to HTML. How will the new-format PEPs be converted to HTML?)

누가 기존 PEPs를 `reStructuredText`로 변환할까요? (Who’s going to convert the existing PEPs to reStructuredText?)

README 및 기타 보조 파일에 `reStructuredText`를 사용하는 이유는 무엇인가요? (Why use reStructuredText for README and other ancillary files?)

Python 표준 라이브러리 모듈의 docstring은 `reStructuredText`로 변환될까요? (Will the docstrings in the Python standard library modules be converted to reStructuredText?)

모든 문자열을 유니코드로 작성하고 싶습니다. 문제가 생길까요? (I want to write all my strings in Unicode. Will anything break?)

커뮤니티에 새로운 구조화된 텍스트 디자인이 필요한 이유는 무엇인가요? (Why does the community need a new structured text design?)

기존 문서화 방법론에 문제가 있나요? (What is wrong with existing documentation methodologies?)

저작권 (Copyright)

감사의 말 (Acknowledgements)

Comments

PEP 287 – reStructuredText Docstring Format

개요 (Abstract)

장점 (Benefits)

목표 (Goals)

배경 (Rationale)

명세 (Specification)

Docstring 관련 주요 기능 (Docstring-Significant Features)

마크업 이스케이프 메커니즘 (Markup escaping mechanism)

Python 소스 코드 및 Python 대화형 세션 포함 마크업: 인라인 리터럴, 리터럴 블록, doctest 블록 (Markup to include Python source code and Python interactive sessions: inline literals, literal blocks, and doctest blocks)

Python 식별자를 분리하는 마크업: 해석된 텍스트 (Markup that isolates a Python identifier: interpreted text)

Python 식별자를 분리하고 그 유형을 지정하는 마크업: 역할이 있는 해석된 텍스트 (Markup that isolates a Python identifier and specifies its type: interpreted text with roles)

“태그 목록” 또는 “레이블 목록”을 위한 마크업: 필드 목록 (Markup for “tagged lists” or “label lists”: field lists)

마크업 확장성: 지시문 및 대체 (Markup extensibility: directives and substitutions)

섹션 구조 마크업 (Section structure markup)

질문 및 답변 (Questions & Answers)

reStructuredText는 충분히 풍부한가요? (Is reStructuredText rich enough?)

reStructuredText는 너무 풍부한가요? (Is reStructuredText too rich?)

StructuredText처럼 섹션 구조에 들여쓰기를 사용하지 않는 이유는 무엇인가요? 더 “Pythonic”하지 않나요? (Why not use indentation for section structure, like StructuredText does? Isn’t it more “Pythonic”?)

PEPs에 reStructuredText를 사용하는 이유는 무엇인가요? 기존 표준의 문제점은 무엇인가요? (Why use reStructuredText for PEPs? What’s wrong with the existing standard?)

docstring 및 PEP 제안을 분리하는 것이 더 낫지 않을까요? (Wouldn’t it be better to keep the docstring and PEP proposals separate?)

기존 pep2html.py 스크립트는 기존 PEP 형식을 HTML로 변환합니다. 새 형식의 PEP는 어떻게 HTML로 변환될까요? (The existing pep2html.py script converts the existing PEP format to HTML. How will the new-format PEPs be converted to HTML?)

누가 기존 PEPs를 reStructuredText로 변환할까요? (Who’s going to convert the existing PEPs to reStructuredText?)

README 및 기타 보조 파일에 reStructuredText를 사용하는 이유는 무엇인가요? (Why use reStructuredText for README and other ancillary files?)

Python 표준 라이브러리 모듈의 docstring은 reStructuredText로 변환될까요? (Will the docstrings in the Python standard library modules be converted to reStructuredText?)

모든 문자열을 유니코드로 작성하고 싶습니다. 문제가 생길까요? (I want to write all my strings in Unicode. Will anything break?)

커뮤니티에 새로운 구조화된 텍스트 디자인이 필요한 이유는 무엇인가요? (Why does the community need a new structured text design?)

기존 문서화 방법론에 문제가 있나요? (What is wrong with existing documentation methodologies?)

저작권 (Copyright)

감사의 말 (Acknowledgements)

Comments

`reStructuredText`는 충분히 풍부한가요? (Is reStructuredText rich enough?)

`reStructuredText`는 너무 풍부한가요? (Is reStructuredText too rich?)

PEPs에 `reStructuredText`를 사용하는 이유는 무엇인가요? 기존 표준의 문제점은 무엇인가요? (Why use reStructuredText for PEPs? What’s wrong with the existing standard?)

누가 기존 PEPs를 `reStructuredText`로 변환할까요? (Who’s going to convert the existing PEPs to reStructuredText?)

README 및 기타 보조 파일에 `reStructuredText`를 사용하는 이유는 무엇인가요? (Why use reStructuredText for README and other ancillary files?)

Python 표준 라이브러리 모듈의 docstring은 `reStructuredText`로 변환될까요? (Will the docstrings in the Python standard library modules be converted to reStructuredText?)