PEP 287 – reStructuredText 독스트링 형식

Author:

David Goodger <goodger at python.org>

Discussions-To:

Doc-SIG list

Status:

Active

Type:

Informational

Created:

25-Mar-2002

Post-History:

02-Apr-2002

Replaces:

216

---

Table of Contents

• 개요
• 이점
• 목표
• 근거
• 명세
• Docstring에 중요한 기능
• 질문과 답변
• 참고 자료 및 각주
• Copyright
• Acknowledgements

번역·라이선스 안내

이 비공식 한국어 번역은 원문 Copyright 절의 Public Domain 조건에 따라 제공합니다. 원저자와 공식 원문은 그대로 표시합니다. 수정되지 않은 기준 원문 · 공식 최신판

개요

평문이 인라인 문서화에 충분히 표현력을 갖추지 못하는 경우, Python 프로그래머들은 독스트링을 위한 형식을 찾아왔습니다. 이 PEP는 reStructuredText markup이 Python 독스트링의 구조화된 평문 문서화를 위한 표준 마크업 형식으로, 그리고 PEP와 부속 문서에도 채택되어야 한다고 제안합니다. reStructuredText는 풍부하고 확장 가능하면서도 읽기 쉬운, 보는 그대로 결과를 얻는(WYSIWYG) 평문 마크업 문법입니다.

여기서는 독스트링의 저수준 문법만을 다룹니다. 이 PEP는 독스트링의 의미론이나 처리에 대해서는 전혀 다루지 않습니다(“독스트링 PEP 로드맵”에 대해서는 PEP 256을 참조하십시오). 또한 이는 항상 정당한 방식으로 남을 순수 평문 독스트링을 폐기하려는 시도도 아닙니다. reStructuredText 마크업은 더 표현력 있는 독스트링을 원하는 사람들을 위한 대안입니다.

이점

프로그래머는 천성적으로 게으른 종족입니다. 우리는 함수, 클래스, 모듈, 서브시스템을 이용해 코드를 재사용합니다. 독스트링 문법을 통해 Python은 코드 내부에서 직접 문서화를 할 수 있게 해줍니다. Python 문서화 특별 관심 그룹(Doc-SIG)의 “성배”는 자동 문서화를 가능케 하는 마크업 문법과 도구 모음이었으며, 이를 통해 Python 시스템의 독스트링을 문맥에 맞게 추출하여 다양한 목적에 유용하고 고품질인 문서로 가공할 수 있습니다.

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

이 마크업은 원본 텍스트에서의 손쉬운 가독성을 유지하면서도 기능성과 표현력을 제공합니다. 처리된 형태(HTML 등)는 이 모든 것을 독자가 이용할 수 있게 해줍니다: 인라인 활성 하이퍼링크; 각주로/각주로부터의 활성 링크; 자동 목차(활성 링크 포함!); 표; 다이어그램 등을 위한 이미지; 보기 좋고 읽기 쉬운 스타일이 적용된 텍스트.

reStructuredText 파서는 Docutils 프로젝트의 일부로서 현재 이용할 수 있습니다. 독립형 reStructuredText 문서와 PEP는 HTML로 변환할 수 있으며, 그 외의 출력 형식 라이터는 작업이 진행 중이고 시간이 지나면 이용할 수 있게 될 것입니다. 독스트링으로부터 자동 문서화를 구현할 Python 소스 “리더(Reader)”에 대한 작업이 진행되고 있습니다. 기존 자동 문서화 도구의 제작자들은 reStructuredText 파서를 자신의 프로젝트에 통합하거나, 더 나아가 힘을 합쳐 Python 표준 라이브러리를 위한 세계적 수준의 도구 모음을 만들어낼 것을 권장합니다.

가까운 미래에는 프로그래머가 온라인 도움말용 HTML, 다양한 목적의 XML, 그리고 궁극적으로는 인쇄 문서용 PDF, DocBook, LaTeX를 기존 독스트링으로부터 사실상 “공짜로” 생성할 수 있게 해주는 도구가 등장할 것입니다. 표준을 채택하면 적어도 더 이상 “바퀴를 재발명하는” 일을 막음으로써 독스트링 처리 도구에 도움이 될 것입니다.

결국에는 기존에 존재하는 유일한 표준 자동 문서화 도구인 PyDoc에 reStructuredText 지원이 추가될 수 있습니다. 그때까지는 모든 독스트링을 미리 서식이 지정된 평문으로 취급하기 때문에 reStructuredText 마크업에도 아무 문제가 없을 것입니다.

목표

다음은 Doc-SIG에서 논의된, 독스트링 형식에 대해 일반적으로 받아들여지는 목표들입니다:

1. 이는 평범한 독자가 원본 형태로도 읽을 수 있어야 합니다.
2. 표준적인 텍스트 편집기라면 어떤 것으로도 쉽게 입력할 수 있어야 합니다.
3. 모듈을 파싱해서 알아낼 수 있는 정보를 담고 있을 필요는 없어야 합니다.
4. 합리적인 어떤 마크업 형식으로도 변환될 수 있도록 충분한 정보(구조)를 담고 있어야 합니다.
5. 마크업 언어에 얽매인다는 느낌 없이 모듈 전체의 문서를 docstring으로 작성할 수 있어야 합니다.

reStructuredText는 이러한 목표를 모두 충족하고 그 이상을 달성하며, 훨씬 더 엄격한 자체 목표까지 설정합니다. 아래의 Docstring-Significant Features를 참고하십시오.

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

1. reStructuredText를 docstring(파이썬 모듈과 패키지의 인라인 문서), PEP, README 형태의 파일, 그리고 그 밖의 독립 문서를 위한 표준 구조화된 평문 형식으로 확립하는 것입니다. “Accepted” 상태는 파이썬 커뮤니티의 합의와 최종적인 BDFL 선언을 통해 얻고자 합니다.

   reStructuredText는 유일한 표준이 아니라 하나의 표준으로 제안되고 있다는 점에 유의하십시오. 이를 사용하는 것은 전적으로 선택 사항입니다. 사용하고 싶지 않은 사람은 사용하지 않아도 됩니다.

2. 파이썬 커뮤니티가 제기하는 관련 우려 사항들을 구하고 다루는 것입니다.
3. 커뮤니티의 지지를 이끌어내는 것입니다. 경쟁하는 여러 마크업이 난립하는 한, 개발 커뮤니티는 계속 분열된 채로 남아 있게 됩니다. 일단 표준이 존재하게 되면 사람들은 그것을 사용하기 시작할 것이고, 그 흐름은 필연적으로 힘을 얻게 될 것입니다.
4. 관련된 자동 문서화 프로젝트들의 노력을 통합하는 것입니다. 관심 있는 개발자들이 힘을 합쳐 공동/병합/통합 구현에 힘써 주기를 바랍니다.

일단 reStructuredText가 파이썬의 표준이 되고 나면, 표준을 놓고 논쟁하는 대신 도구에 노력을 집중할 수 있습니다. 파이썬에는 표준화된 문서화 도구 모음이 필요합니다.

PEP와 관련해서는, 다음 두 전략 중 하나 또는 둘 다를 적용할 수 있습니다.

1. 기존 PEP 절 구조 구성 요소(한 줄짜리 절 제목, 들여쓰기된 본문 텍스트)를 유지합니다. 하위 절은 금지하거나, 들여쓰기된 본문 텍스트 안에서 reStructuredText 스타일의 밑줄 친 제목으로 지원할 수 있습니다.
2. 기존 PEP 절 구조 구성 요소를 reStructuredText 문법으로 대체합니다. 절 제목에는 밑줄이 필요하며, 하위 절은 기본적으로 지원되고, (블록 인용을 제외하면) 본문 텍스트는 들여쓸 필요가 없습니다.

전략 (b)가 권장되며, 그 구현은 완료된 상태입니다.

PEP용 reStructuredText 파서에는 RFC 2822 헤더에 대한 지원이 추가되었습니다(특정 맥락, 즉 문서의 첫 번째 연속 블록에서는 모호함이 없습니다). 통일성을 위해 PEP 절 제목에 어떤 위/아래 밑줄 스타일이 허용되는지 구체적으로 명시하는 것이 바람직할 수 있습니다.

근거

docstring에 대한 표준 문법의 부재는 docstring을 표준 형식(예: HTML, DocBook, TeX)의 문서로 추출·변환하기 위한 표준 도구 개발을 저해해 왔습니다. 그동안 여러 마크업 형식과 그 변형들이 제안되었고 이러한 제안들에 딸린 여러 도구가 있었지만, 표준 docstring 형식이 없었기 때문에 강력한 지지를 얻지 못했거나 절반쯤 완성된 채로 흐지부지되었습니다.

Doc-SIG가 존재해 온 기간 내내, 단일한 표준 docstring 형식에 대한 합의는 한 번도 이루어진 적이 없습니다. 다음과 같은 이유(들 중 일부)로 가볍고 암묵적인 마크업이 추구되어 왔습니다.

1. Python 코드 내에 작성된 독스트링은 대화형 인터프리터 내에서 사용할 수 있으며, “출력”할 수 있습니다. 따라서 쉬운 가독성을 위해 일반 텍스트를 사용합니다.
2. 프로그래머는 원시 독스트링의 가독성을 희생하지 않으면서 독스트링에 구조를 추가하기를 원합니다. 꾸미지 않은 일반 텍스트는 유용한 구조화된 형식으로 변환(“상위 변환”)할 수 없습니다.
3. (XML이나 TeX 같은) 명시적 마크업은 초심자에게 읽기 어렵다고 널리 여겨집니다.
4. 암묵적 마크업은 깔끔하고 미니멀한 Python 구문과 미학적으로 어울립니다.

독스트링을 위한 여러 대안 마크업이 수년간 Doc-SIG에서 제안되어 왔으며, 대표적인 예시는 아래에 나열되어 있습니다. 각각은 위에서 언급한 목표에 따라 간략히 분석됩니다. 이는 기존의 모든 마크업 시스템을 망라하는 목록이 되도록 의도된 것은 아니라는 점에 유의하십시오. 여기서 언급되지 않은 다른 여러 마크업(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

  초기에는 Zope Corp의 StructuredText를 비롯한 Setext(Structure Enhanced Text)의 변형들이 Python 독스트링 포맷팅용으로 제안되었습니다. 이후로 이러한 변형들은 통칭하여 “STexts”라고 부릅니다. STexts는 특별한 지식 없이도 읽기 쉽고 작성하기도 비교적 쉽다는 장점이 있습니다.

  일부에서 사용되고 있음에도 불구하고(기존의 대부분의 Python 자동 문서화 도구를 포함하여), STexts는 지금까지 표준으로 자리 잡지 못했는데, 그 이유는 다음과 같습니다.

  • STexts는 불완전했습니다. 사람들이 docstring에서 사용하고 싶어하는 “필수적인” 구성 요소가 부족하여, STexts는 이상적인 것과는 거리가 멀게 되었습니다. 이러한 “필수적인” 구성 요소는 보편적이지 않다는 점에 유의하십시오. 모든 사람에게는 각자의 요구 사항이 있습니다.
  • STexts는 때때로 놀라움을 주었습니다. 텍스트의 일부가 예상치 못하게 마크업으로 해석되어, 사용자에게 불편을 초래했습니다.
  • SText 구현체에는 버그가 있었습니다.
  • 대부분의 STexts는 구현체 자체를 제외하고는 공식 명세가 없습니다. 버그가 있는 구현체는 곧 버그가 있는 명세를 의미했으며, 그 반대도 마찬가지였습니다.
  • 마크업 문자가 마크업이 아닌 맥락에서 사용될 때 SText 마크업 규칙을 우회할 메커니즘이 없었습니다. 즉, 마크업을 이스케이프할 방법이 없었습니다.

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

reStructuredText는 SText 개념을 완전히 개정하고 재해석한 것으로, 위에 나열된 모든 문제를 해결합니다.

명세

reStructuredText의 명세와 사용자 문서는 상당히 방대합니다. 여기서 모든 것을 반복하거나 요약하는 대신, 원본에 대한 링크를 제공합니다.

먼저 짧고 부드러운 입문서인 A ReStructuredText Primer를 살펴보십시오. Quick reStructuredText 사용자 참조 문서는 모든 마크업 구성 요소를 간략히 요약합니다. 완전하고 상세한 내용은 다음 문서를 참조하십시오:

• An Introduction to reStructuredText
• reStructuredText Markup Specification
• reStructuredText Directives

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

Docstring에 중요한 기능

• 마크업 이스케이프 메커니즘.

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

• Python 소스 코드와 Python 대화형 세션을 포함하는 마크업: 인라인 리터럴, 리터럴 블록, doctest 블록.

  인라인 리터럴은 프로그램 입출력이나 코드 스니펫을 나타내기 위해 이중 백쿼트를 사용합니다. 인라인 리터럴 내부에서는 마크업 해석(백슬래시 이스케이프[\] 해석 포함)이 이루어지지 않습니다.

  리터럴 블록(코드 발췌나 ASCII 그래픽과 같은 블록 수준의 리터럴 텍스트)은 들여쓰기되며, 앞 단락 끝에 이중 콜론(“::”)으로 표시됩니다(바로 여기 –>):

  if literal_block:
      text = 'is left as-is'
      spaces_and_linebreaks = 'are preserved'
      markup_processing = None
  

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

  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 식별자를 구분하는 마크업: 해석 텍스트(interpreted text).

  백틱(backquote) 하나로 둘러싸인 텍스트는 “해석 텍스트(interpreted text)”로 인식되며, 그 해석은 애플리케이션에 따라 달라집니다. Python docstring 맥락에서, 해석 텍스트의 기본 해석은 Python 식별자로 취급하는 것입니다. 이 텍스트는 주어진 식별자에 대한 문서와 연결된 하이퍼링크로 마크업됩니다. 조회 규칙은 Python 자체와 동일합니다: LGB 네임스페이스 조회(로컬, 전역, 내장). 해석 텍스트의 “역할(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 식별자를 구분하고 그 타입을 지정하는 마크업: 역할이 있는 해석 텍스트.

  Python 소스 컨텍스트 리더는 명시적 역할을 요구하지 않도록 설계되었지만, 명시적 역할을 사용할 수도 있습니다. 식별자를 명시적으로 분류하려면, 역할을 식별자와 함께 접두사 또는 접미사 형태로 지정합니다:

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

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

• “태그된 목록(tagged lists)” 또는 “레이블 목록(label lists)”을 위한 마크업: 필드 목록.

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

  수정된 RFC 2822 구문이 사용되며, 필드 이름 앞뿐만 아니라 뒤에도 콜론이 붙습니다. 필드 본문 역시 더 다재다능하여, 여러 필드 본문(중첩된 필드 목록까지도)을 포함할 수 있습니다. 예를 들면:

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

  표준 RFC 2822 헤더 구문은 모호하기 때문에 이 구조에 사용할 수 없습니다. 줄 시작 부분에 콜론이 뒤따르는 단어는 일반 텍스트에서 흔합니다.

• 마크업 확장성: 지시어(directive)와 치환(substitution).

  지시어는 reStructuredText의 확장 메커니즘으로 사용되며, 새로운 구문을 추가하지 않고도 새로운 블록 수준 구조에 대한 지원을 추가하는 방법입니다. 이미지, 경고문(admonition, 참고·주의 등), 목차 생성(그 외에도) 등을 위한 지시어가 구현되어 있습니다. 예를 들어, 다음은 이미지를 배치하는 방법입니다:

  .. image:: mylogo.png
  

  치환 정의를 사용하면 블록 수준 지시어의 강력함과 유연성을 인라인 텍스트에서도 공유할 수 있습니다. 예를 들면:

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

• 섹션 구조 마크업.

  reStructuredText에서 섹션 헤더는 들여쓰기가 아니라 밑줄(그리고 경우에 따라 윗줄)을 통한 장식을 사용합니다. 예를 들면 다음과 같습니다.:

  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.
  

질문과 답변

1. reStructuredText는 충분히 풍부합니까?

   대부분의 사람들에게는 그렇습니다. 특정 응용에 필요한 구성이 부족하다면, 지시어(directive) 메커니즘을 통해 추가할 수 있습니다. 유용하고 흔한 구성이 간과되었고 적절히 읽기 쉬운 구문을 찾을 수 있다면, 명세와 파서에 추가할 수 있습니다.

2. reStructuredText는 너무 풍부합니까?

   특정 응용이나 개인에게는 그럴 수 있습니다. 일반적으로는 그렇지 않습니다.

   아주 초기부터, Doc-SIG에서 docstring 마크업 구문이 제안될 때마다 누군가는 어떤 구성에 대한 지원이 부족하다고 불평해 왔습니다. “이것은 docstring에 관한 이야기이고, docstring에는 복잡한 마크업이 있어서는 안 됩니다.”라는 식의 답변이 자주 나왔습니다. 문제는 한 사람에게는 불필요해 보이는 구성이 다른 사람에게는 절대적으로 필수적일 수 있다는 점입니다.

   reStructuredText는 그 반대의 접근 방식을 취합니다. 즉 (명시적 마크업을 위한 범용 확장 메커니즘에 더해) 풍부한 암시적 마크업 구성 집합을 제공하여 온갖 종류의 문서를 가능하게 합니다. 특정 응용에 대해 구성 집합이 너무 풍부하다면, (응용별 재정의를 통해) 사용하지 않는 구성을 파서에서 제거하거나, 관례적으로 단순히 생략할 수 있습니다.

3. StructuredText가 하듯이 섹션 구조에 들여쓰기를 사용하지 않는 이유는 무엇입니까? 그것이 더 “파이썬스럽지” 않습니까?

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

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

   저는 들여쓰기를 사용하는 것이 파이썬스럽다는 주장을 거부합니다. 텍스트는 코드가 아니며, 서로 다른 전통과 관습이 존재합니다. 사람들은 30세기가 넘는 시간 동안 가독성을 위해 텍스트를 표현해 왔습니다. 불필요하게 혁신하지 맙시다.

   더 자세한 설명은 Problems With StructuredText의 Section Structure via Indentation를 참조하십시오.

4. PEP에 왜 reStructuredText를 사용합니까? 기존 표준에는 무엇이 잘못되었습니까?

   PEP를 위한 기존 표준은 전반적인 표현력 면에서 매우 제한적이며, 이처럼 참조가 풍부한 문서 유형에 특히 참조 기능이 부족합니다. PEP는 현재 HTML로 변환되지만, 그 결과(대부분 고정폭 텍스트)는 그다지 매력적이지 않으며, HTML의 부가가치 잠재력(특히 인라인 하이퍼링크) 대부분이 활용되지 않고 있습니다.

   reStructuredText를 PEP의 표준 마크업으로 채택하면 섹션 구조, 인라인 마크업, 그래픽, 표 지원을 포함해 훨씬 더 풍부한 표현이 가능해집니다. 여러 PEP에는 ASCII 그래픽 다이어그램이 있는데, 이는 일반 텍스트 문서가 지원할 수 있는 전부입니다. PEP가 HTML 형식으로도 제공되는 만큼, 제대로 된 다이어그램을 포함할 수 있는 기능은 즉시 유용할 것입니다.

   현재 PEP 관행에서는 본문에 “[1]” 형태의 참조 표시자를 사용할 수 있으며, 각주/참조 자체는 문서 끝부분의 한 섹션에 나열됩니다. 현재는 참조 표시자와 각주/참조 자체 사이에 하이퍼링크가 없습니다(pep2html.py에 이를 추가하는 것도 가능하겠지만, 현재 상태의 “마크업”은 모호해서 실수가 불가피할 것입니다). 참조가 많은 PEP(이 문서처럼요 ;-)는 앞뒤로 왔다갔다 넘겨봐야 하는 일이 많습니다. PEP를 수정할 때는 흔히 새 참조가 추가되거나 사용되지 않는 참조가 삭제됩니다. 참조 번호를 매기려면 두 곳에서 작업해야 하고 연쇄적인 영향이 발생할 수 있어 번거롭습니다(참조 1을 새로 하나 삽입하면 다른 모든 참조의 번호를 다시 매겨야 하며, 항상 새 참조를 끝에 추가하는 것도 최선은 아닙니다). 참조들이 서로 어긋나기 쉽습니다.

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

   Abstract
   
       This PEP proposes adding frungible doodads [1] to the core.
       It extends PEP 9876 [2] via the BCA [3] mechanism.
   
   ...
   
   References and Footnotes
   
       [1] http://www.example.org/
   
       [2] PEP 9876, Let's Hope We Never Get Here
           http://peps.python.org/pep-9876/
   
       [3] "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” 섹션은 문서 트리 변환을 통해 자동으로 생성될 수 있습니다. 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
   

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

5. docstring 제안과 PEP 제안을 분리해 두는 편이 더 낫지 않겠습니까?

   PEP 마크업에 대한 필요성이 없다고 판단되면 PEP 마크업 제안은 제거될 수 있으며, 혹은 별도의 PEP로 만들어질 수도 있습니다. 채택될 경우, PEP 목적 및 지침(PEP 1)과 샘플 PEP 템플릿(PEP 9)이 갱신될 것입니다.

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

6. 기존의 pep2html.py 스크립트는 기존 PEP 형식을 HTML로 변환합니다. 새 형식의 PEP는 어떻게 HTML로 변환됩니까?

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

7. 기존 PEP를 reStructuredText로 변환하는 것은 누가 하게 됩니까?

   PEP 작성자나 자원봉사자가 원한다면 기존 PEP를 변환할 수 있지만, 그렇게 해야 할 의무는 없습니다. reStructuredText 기반 PEP는 기존 PEP 표준과 공존하게 됩니다. 답변 6에서 언급한 pep2html.py는 기존 표준과 새 표준을 모두 처리합니다.

8. README 및 기타 부속 파일에 reStructuredText를 사용하는 이유는 무엇입니까?

   위 답변 4에서 PEP에 대해 제시된 논거는 README 및 기타 부속 파일에도 마찬가지로 적용됩니다. 표준 마크업을 채택함으로써, 이러한 파일들을 상호 참조가 가능한 보기 좋은 HTML로 변환하여 python.org에 게시할 수 있습니다. 다른 프로젝트의 개발자들도 자신의 문서 작업에 이 기능을 활용할 수 있습니다.

9. 기존 마크업 관례와의 피상적인 유사성이 문제를 일으켜, 사람들이 (일반 텍스트가 자연스러워 보이기 때문에 알아차리지 못한 채) 유효하지 않은 마크업을 작성하게 되지는 않겠습니까? reStructuredText는 “정확하지 않은” 마크업에 대해 얼마나 관대합니까?

   한 프로그래밍 언어에서 다른 언어로 옮겨갈 때 그렇듯이, 다소의 시행착오가 있을 것입니다. 어떤 언어든 마찬가지로, 숙련도는 경험을 통해 늘어납니다. 다행히도 reStructuredText는 실제로 매우 작은 언어입니다.

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

   엄격한 의미에서, reStructuredText 파서는 매우 엄격합니다(마땅히 그래야 하는데, “모호함에 직면했을 때는 추측하고자 하는 유혹을 뿌리쳐라”는 컴퓨터 언어 파싱뿐 아니라 마크업 파싱에도 적용되기 때문입니다). 다음은 An Introduction to reStructuredText의 설계 목표 3입니다.

   모호하지 않을 것. 마크업 규칙은 해석의 여지가 있어서는 안 됩니다. 주어진 입력에 대해, 가능한 출력(오류 출력 포함)은 오직 하나여야 합니다.

   엄격하기는 하지만, 동시에 파서는 유용한 진단 출력(“시스템 메시지”)을 생성함으로써 도움을 주고자 합니다. 파서는 문제를 보고할 때 그 심각도 수준(낮은 것부터 높은 순으로 디버그, 정보, 경고, 오류, 심각)을 함께 표시합니다. 사용자나 클라이언트 소프트웨어가 보고 임계값을 결정할 수 있으며, 낮은 수준의 문제는 무시하거나 높은 수준의 문제는 처리를 즉시 중단시키도록 할 수 있습니다. 문제는 파싱 도중 보고될 뿐만 아니라 출력에도 포함되며, 문제의 발생 지점과 이를 설명하는 시스템 메시지 사이에 양방향 링크가 걸리는 경우가 많습니다.

10. Python 표준 라이브러리 모듈의 독스트링이 reStructuredText로 변환됩니까?

    아닙니다. Python의 라이브러리 참조 문서는 소스와 별도로 유지 관리됩니다. Python 표준 라이브러리의 독스트링은 라이브러리 참조 문서를 중복하려 해서는 안 됩니다. Python 표준 라이브러리의 독스트링에 대한 현재 방침은, (비록 많은 독스트링이 임의적인 암묵적 마크업을 포함하고 있기는 하지만) 그것들이 간결한 힌트, 즉 단순하고 마크업이 없는 수준을 넘어서지 않아야 한다는 것입니다.

11. 저는 제 모든 문자열을 유니코드로 작성하고 싶습니다. 무언가가 깨지겠습니까?

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

12. 커뮤니티는 왜 새로운 구조화 텍스트 설계가 필요할까요?

    기존의 구조화된 텍스트 설계는 위의 “근거”에서 제시된 이유로 인해 결함이 있습니다. reStructuredText는 “읽기 쉬운 평문” 매체가 갖는 한계 내에서 완전한 마크업 구문이 되는 것을 목표로 합니다.

13. 기존 문서화 방법론의 어떤 점이 잘못되었습니까?

    어떤 기존 방법론을 말합니까? Python 독스트링의 경우, JavaDoc과 유사한 문서화 방법론은커녕 공식 표준 마크업 형식조차 없습니다. 방법론에 관한 문제는 (본 PEP가 다루는) 구문보다 훨씬 상위 수준의 문제입니다. 이는 잠재적으로 훨씬 더 논란의 여지가 있고 해결하기 어려운 문제이며, 이 논의에서는 의도적으로 제외되었습니다.

참고 자료 및 각주

Copyright

This document has been placed in the public domain.

Acknowledgements

Some text is borrowed from PEP 216, Docstring Format, by Moshe Zadka.

Special thanks to all members past & present of the Python Doc-SIG.