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는 일반적인 독스트링 처리 시스템(DPS) 프레임워크를 제안합니다. 이 프레임워크는 구성 요소를 (프로그램적 구성 요소와 개념적 구성 요소로) 분리하여, 개별 문제를 합의(하나의 해결책) 또는 분화(여러 해결책)를 통해 해결할 수 있게 합니다. 또한 다양한 플러그인 구성 요소(입력 컨텍스트 리더, 마크업 파서 및 출력 형식 작성기)를 사용할 수 있도록 표준 인터페이스를 장려합니다.

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

독스트링 PEP 로드맵

독스트링 처리에는 여러 측면이 있습니다. “Docstring PEPs”는 각 문제를 독립적으로, 또는 가능한 한 독립적으로 다루기 위해 문제를 나누었습니다. 개별 측면과 관련 PEP는 다음과 같습니다.

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

문제를 분리하면 더 쉽게 합의를 도출하고(더 작은 논쟁 ;-), 분화를 더 기꺼이 받아들일 수 있습니다.

근거

일부 다른 언어에는 표준 인라인 문서화 시스템이 있습니다. 예를 들어 Perl에는 POD(“Plain Old Documentation”)가 있고 Java에는 Javadoc가 있지만, 둘 다 Python다운 방식과는 잘 맞지 않습니다. 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 대화형 인터프리터 내부, 셸 명령줄 및 웹 브라우저(HTML)의 GUI 창에서 독스트링을 추출하고 표시합니다. PyDoc은 매우 유용한 도구이지만 다음과 같은 몇 가지 부족한 점이 있습니다.

GUI/HTML의 경우 식별자 이름에 일부 경험적 하이퍼링크를 적용하는 것을 제외하면 독스트링의 서식이 지정되지 않습니다. 원치 않는 줄바꿈을 방지하기 위해 <p><small><tt> 태그 안에 표시됩니다. 안타깝게도 결과는 매력적이지 않습니다.
PyDoc은 가져온 모듈 객체에서 독스트링과 구조적 정보(클래스 식별자, 메서드 시그니처 등)를 추출합니다. 신뢰할 수 없는 코드를 가져오는 것과 관련된 보안 문제가 있습니다. 또한 가져오는 과정에서 주석, “추가 독스트링”(독스트링이 아닌 컨텍스트의 문자열 리터럴; PEP 258 참조), 정의 순서와 같은 소스의 정보가 손실됩니다.

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

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

명세

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

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

구성 요소 1, 2/3/5, 4는 각각 별도의 동반 PEP의 대상입니다. 프레임워크나 구문/파서의 또 다른 구현이 존재할 경우, 추가 PEP가 필요할 수 있습니다. 구성 요소 6과 7 각각에 대해 여러 구현이 필요할 것이며, 이러한 구성 요소에는 PEP 메커니즘이 과할 수 있습니다.