PEP 256 – 독스트링 처리 시스템 프레임워크

Author:: David Goodger <goodger at python.org>
Discussions-To:: Doc-SIG list
Status:: Rejected
Type:: Standards Track
Created:: 01-Jun-2001
Post-History:: 13-Jun-2001

Table of Contents

거부 공지
초록
독스트링 PEP 로드맵
근거
- PyDoc 및 기타 기존 시스템
명세
프로젝트 웹 사이트
참고 문헌 및 각주
Copyright
Acknowledgements

번역·라이선스 안내

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

Python은 인라인 문서화에 적합합니다. 내장 독스트링 문법 덕분에 Python에서는 제한된 형태의 Literate Programming을 쉽게 할 수 있습니다. 그러나 Python 독스트링을 추출하고 처리하기 위한 만족스러운 표준 도구는 없습니다. 표준 도구 모음이 없다는 점은 Python 인프라의 중대한 공백이며, 이 PEP는 그 공백을 메우는 것을 목표로 합니다.

독스트링 처리를 둘러싼 문제들은 논란이 많았고 해결하기도 어려웠습니다. 이 PEP는 범용 독스트링 처리 시스템(Docstring Processing System, DPS) 프레임워크를 제안합니다. 이 프레임워크는 구성 요소(프로그램적 구성 요소와 개념적 구성 요소)를 분리하여, 개별 문제를 합의(하나의 해법)나 분화(여러 해법)를 통해 해결할 수 있게 합니다. 또한 다양한 플러그인 구성 요소(입력 컨텍스트 리더, 마크업 파서, 출력 형식 라이터)를 사용할 수 있게 하는 표준 인터페이스를 장려합니다.

DPS 프레임워크의 개념은 구현 세부 사항과 독립적으로 제시됩니다.

독스트링 PEP 로드맵

독스트링 처리에는 여러 측면이 있습니다. “독스트링 PEP”들은 각 문제를 따로따로, 또는 가능한 한 그에 가깝게 다루기 위해 문제들을 나누었습니다. 개별 측면과 관련 PEP는 다음과 같습니다:

독스트링 문법. PEP 287, “reStructuredText Docstring Format”은 Python 독스트링, PEP 및 기타 용도를 위한 문법을 제안합니다.
독스트링 의미론은 적어도 두 가지 측면으로 구성됩니다:
- 관례: 독스트링의 상위 수준 구조입니다. PEP 257의 “독스트링 규약”에서 다룹니다.
- 방법론: 독스트링의 정보 내용에 대한 규칙입니다. 다루지 않습니다.
처리 메커니즘. 이 PEP(PEP 256)는 추상 독스트링 처리 시스템(DPS)의 상위 수준 문제와 명세를 개괄합니다. PEP 258, “Docutils Design Specification”은 개발 중인 한 DPS의 설계와 구현에 대한 개요입니다.
출력 스타일: 개발자들은 자신의 소스 코드에서 생성된 문서가 보기 좋기를 원하며, 그것이 무엇을 의미하는지에 대해서는 다양한 생각이 있습니다. PEP 258은 “Stylist Transforms”를 간략히 다룹니다. 독스트링 처리의 이 측면은 아직 충분히 탐구되지 않았습니다.

문제들을 분리함으로써 더 쉽게 합의를 이룰 수 있고(싸움이 작아집니다 ;-), 분화도 더 기꺼이 받아들일 수 있습니다.

근거

다른 몇몇 언어에는 표준 인라인 문서화 시스템이 있습니다. 예를 들어 Perl에는 POD (“Plain Old Documentation”)가 있고 Java에는 Javadoc이 있지만, 둘 다 파이썬다운 방식과는 잘 맞지 않습니다. POD 문법은 매우 명시적이지만, 가독성 면에서는 Perl을 닮았습니다. Javadoc은 HTML 중심입니다. “@field” 태그를 제외하면 마크업에 원시 HTML을 사용합니다. 여러 언어에 유용한 Autoduck과 Web (Tangle & Weave) 같은 범용 도구도 있습니다.

Python용 자동 문서화 시스템을 작성하려는 시도는 많이 있었습니다(전체 목록은 아닙니다):

Marc-Andre Lemburg의 doc.py
Daniel Larsson의 pythondoc 및 gendoc
Doug Hellmann의 HappyDoc
Laurence Tratt의 Crystal(더 이상 웹에서 구할 수 없습니다)
Ka-Ping Yee의 pydoc (pydoc.py는 현재 Python 표준 라이브러리의 일부입니다. 아래를 참조하십시오)
Tony Ibbs의 docutils (Tony는 이 이름을 Docutils project에 기증했습니다)
Edward Loper의 STminus 형식화 및 관련 작업

저마다 다른 목표를 가진 이 시스템들은 다양한 수준의 성공을 거두었습니다. 위 시스템 중 상당수의 문제는 지나친 야심과 유연성 부족이 결합되어 있었다는 점입니다. 이 시스템들은 독스트링 추출 시스템, 마크업 파서, 내부 처리 시스템, 그리고 고정된 스타일을 가진 하나 이상의 출력 형식 작성기로 이루어진 자기 완결적인 구성 요소 집합을 제공했습니다. 필연적으로 각 시스템에는 한 가지 이상의 측면에서 심각한 결점이 있었고, 쉽게 확장하거나 수정할 수도 없었기 때문에 표준 도구로 채택되지 못했습니다.

관련된 모든 당사자가 합의할 수 있는 단일한 자기 완결적 시스템은 있을 수 없으므로, “전부 아니면 전무” 방식은 성공할 수 없다는 점이 (적어도 이 글의 저자에게는) 분명해졌습니다. 구성 요소를 여러 가지로 구현할 수 있는, 확장을 염두에 두고 설계된 모듈식 구성 요소 방식이 성공을 위한 유일한 기회일지도 모릅니다. 표준 구성 요소 간 API는 전체에 대한 상세한 지식 없이도 DPS 구성 요소를 이해할 수 있게 하여 기여의 장벽을 낮추고, 궁극적으로 풍부하고 다양한 시스템을 만들어 낼 것입니다.

독스트링 처리 시스템의 각 구성 요소는 독립적으로 개발되어야 합니다. 기존 시스템들을 병합하거나 새로 개발하거나, 또는 두 방법을 함께 사용하여 “최고 수준”의 시스템을 선정해야 합니다. 이 시스템은 Python 표준 라이브러리에 포함되어야 합니다.

PyDoc 및 기타 기존 시스템

PyDoc은 릴리스 2.1부터 Python 표준 라이브러리의 일부가 되었습니다. PyDoc은 Python 대화형 인터프리터 안에서, 셸 명령줄에서, 그리고 GUI 창에서 웹 브라우저(HTML)로 독스트링을 추출하여 표시합니다. 매우 유용한 도구이기는 하지만, PyDoc에는 다음과 같은 몇 가지 결함이 있습니다:

GUI/HTML의 경우, 식별자 이름에 대한 일부 휴리스틱 하이퍼링크를 제외하면 독스트링에 아무런 서식도 적용되지 않습니다. 원치 않는 줄 바꿈을 피하기 위해 독스트링은 <p><small><tt> 태그 안에 표시됩니다. 안타깝게도 그 결과물은 보기 좋지 않습니다.
PyDoc은 임포트된 모듈 객체에서 독스트링과 구조 정보(클래스 식별자, 메서드 시그니처 등)를 추출합니다. 신뢰할 수 없는 코드를 임포트하는 데에는 보안 문제가 따릅니다. 또한 임포트 과정에서 주석, “추가 독스트링”(독스트링이 아닌 문맥에 있는 문자열 리터럴. PEP 258 참조), 정의 순서 등 소스의 정보가 사라집니다.

이 PEP에서 제안하는 기능은 PyDoc이 HTML 페이지를 제공할 때 PyDoc에 추가되거나 PyDoc에서 사용될 수 있습니다. 제안된 독스트링 처리 시스템의 기능은 현재 형태의 PyDoc에 필요한 것보다 훨씬 많습니다. 독립적인 도구가 개발되거나(PyDoc이 이를 사용할 수도, 사용하지 않을 수도 있습니다), PyDoc이 이 기능을 포괄하도록 확장되어 독스트링 처리 시스템(또는 그러한 시스템 중 하나)이 될 수 있습니다. 이 결정은 이 PEP의 범위를 벗어납니다.

기존의 다른 독스트링 처리 시스템도 마찬가지로, 그 작성자들은 이 프레임워크와의 호환성을 선택할 수도 있고 선택하지 않을 수도 있습니다. 그러나 이 프레임워크가 승인되어 Python 표준으로 채택된다면, 호환성은 이러한 시스템의 향후 방향에서 중요한 고려 사항이 될 것입니다.

명세

독스트링 처리 시스템 프레임워크는 다음과 같이 나뉩니다:

독스트링 규약. 다음과 같은 사항을 문서화합니다:
- 무엇을 어디에 문서화해야 하는지.
- 첫 줄은 한 줄 요약입니다.
PEP 257은 이러한 사항 중 일부를 문서화합니다.
독스트링 처리 시스템 설계 명세. 다음과 같은 사항을 문서화합니다:
- 상위 수준 명세: DPS가 하는 일.
- 실행 가능한 스크립트를 위한 명령줄 인터페이스.
- 시스템 Python API.
- 독스트링 추출 규칙.
- 입력 문맥을 캡슐화하는 리더(Reader).
- 파서(Parser).
- 문서 트리: 중간 단계의 내부 자료 구조. 파서와 리더의 출력, 그리고 라이터의 입력은 모두 같은 자료 구조를 공유합니다.
- 문서 트리를 수정하는 변환(Transform).
- 출력 형식을 위한 라이터(Writer).
- 출력 관리(파일 하나, 여러 파일, 또는 메모리 내 객체)를 담당하는 배포자(Distributor).
이러한 사항은 모든 독스트링 처리 시스템 구현에 적용됩니다. PEP 258이 이러한 사항을 문서화합니다.
독스트링 처리 시스템 구현.
입력 마크업 명세: 독스트링 문법입니다. PEP 287은 표준 문법을 제안합니다.
입력 파서 구현.
입력 컨텍스트 리더(“모드”: Python 소스 코드, PEP, 독립 텍스트 파일, 이메일 등)와 그 구현입니다.
스타일리스트: 일부 입력 컨텍스트 리더에는 스타일리스트가 연결될 수 있으며, 스타일리스트를 통해 다양한 스타일의 출력 문서를 만들 수 있습니다.
출력 형식(HTML, XML, TeX, DocBook, info 등)과 라이터 구현.

구성 요소 1, 2/3/5, 4는 각각 별도의 관련 PEP에서 다룹니다. 프레임워크나 문법/파서의 다른 구현이 있다면 추가 PEP가 필요할 수 있습니다. 구성 요소 6과 7은 각각 여러 구현이 필요할 것입니다. 이러한 구성 요소에는 PEP 절차가 과할 수 있습니다.