MEP10: 독스트링 일관성 #

초록 #

matplotlib는 docstring 사이에 많은 불일치가 있습니다. 이것은 문서를 읽기 어렵게 만들 뿐만 아니라 어떤 사양을 따라야 할지 모르기 때문에 기여자에게도 더 어렵습니다. 일관되게 따르는 명확한 docstring 규칙이 있어야 합니다.

API 설명서의 구성을 따르기가 어렵습니다. pyplot 및 축과 같은 일부 페이지는 방대하고 탐색하기 어렵습니다. 대신 자세한 문서로 연결되는 짧은 요약표가 있어야 합니다. 또한 일부 docstring 자체는 상당히 길고 중복 정보를 포함합니다.

문서 작성은 시간이 오래 걸리고 make.py Makefile이 아닌 스크립트를 사용합니다.

자세한 설명 #

matplotlib가 Sphinx를 사용하기 시작한 이후로 삶을 더 쉽게 만들어주는 새로운 도구와 규칙이 많이 있습니다. 다음은 docstring에 대해 제안된 변경 사항 목록이며, 대부분 이러한 새로운 기능을 포함합니다.

Numpy 독스트링 형식 #

Numpy docstring 형식 : 이 형식은 docstring을 명확한 섹션으로 나누고 각 섹션에는 docstring을 원시 텍스트와 HTML로 쉽게 읽을 수 있도록 하는 다른 구문 분석 규칙이 있습니다. 우리는 대안을 고려하거나 우리 자신을 발명할 수 있지만 이것은 Numpy/Scipy 커뮤니티에서 잘 사용되고 이해되기 때문에 강력한 선택입니다.

matplotlib에 있는 대부분의 docstring은 다른 항목에 연결할 때 명시적인 "역할"을 사용합니다. 예를 들면 다음과 같습니다 :func:`myfunction`. Sphinx 0.4부터는 "obj"로 설정할 수 있는 "default_role"이 있으며, 이는 모든 유형의 Python 개체에 다형적으로 연결됩니다. 이렇게 하면 `myfunction`대신 쓸 수 있습니다. 이렇게 하면 독스트링을 원시 텍스트로 훨씬 더 쉽게 읽고 편집할 수 있습니다. 또한 Sphinx는 현재 모듈을 설정할 `~matplotlib.axes.Axes.set_xlim` 수 있으므로 다음 과 같은 링크를 `~axes.Axes.set_xlim`.

서명 재정의 #

matplotlib의 많은 메서드는 *args및 **kwargs구문을 사용하여 함수에서 허용하는 키워드 인수를 동적으로 처리하거나 다른 함수에 위임합니다. 그러나 이것은 종종 문서의 서명으로 유용하지 않습니다. 이러한 이유로 많은 matplotlib 메서드에는 다음과 같은 것이 포함됩니다.

def annotate(self, *args, **kwargs):
    """
    Create an annotation: a piece of text referring to a data
    point.

    Call signature::

      annotate(s, xy, xytext=None, xycoords='data',
               textcoords='data', arrowprops=None, **kwargs)
    """

이것은 Sphinx에서 구문 분석할 수 없으며 원시 텍스트에서 다소 장황합니다. Sphinx 1.1에서 autodoc_docstring_signatureconfig 값이 True로 설정되면 Sphinx는 docstring의 첫 번째 줄에서 대체 서명을 추출하여 다음을 허용합니다.

def annotate(self, *args, **kwargs):
    """
    annotate(s, xy, xytext=None, xycoords='data',
               textcoords='data', arrowprops=None, **kwargs)

    Create an annotation: a piece of text referring to a data
    point.
    """

명시적 서명은 생성된 문서에서 실제 Python 서명을 대체합니다.

matplotlib에 대해 numpydoc 확장이 켜져 있어야 합니다. 이것들이 matplotlib 소스 트리에 포함되어야 하는지 또는 종속성으로 사용되어야 하는지에 대한 중요한 질문이 있습니다. Numpy 설치는 numpydoc 확장을 얻기에 충분하지 않습니다. 별도의 설치 절차입니다. 어쨌든 우리의 요구 사항에 맞게 사용자 지정이 필요한 정도까지 이러한 변경 사항을 포크하지 않고 업스트림에 제출하도록 노력해야 합니다.
모든 docstring을 수동으로 살펴보고 새로운 형식과 규칙으로 업데이트합니다. 상호 참조 업데이트(에서 `:func:`myfunc`로 `func`)는 반자동화될 수 있습니다. 이것은 매우 바쁜 작업이며 아마도 이 노동력은 단일 개발자에게 과도한 부담을 주지 않도록 모듈별로 나누어야 할 것입니다.
자동 요약 및 sphinx-autogen. 이것은 내러티브 문서에 최소한의 영향을 미치기를 바랍니다.
예제 페이지 생성기( gen_rst.py)를 수정하여 예제에서 모듈 docstring을 추출하고 예제 페이지의 비문자열 부분에 포함합니다.
sphinx-quickstart새로운 스타일의 Sphinx Makefile을 생성하는 데 사용 합니다. 현재의 다음 기능은 make.py다른 방법으로 해결해야 합니다.
- 일부 정적 콘텐츠 복사
- "작은" 빌드 지정(예시를 위한 저해상도 PNG 파일만 해당)

1, 2, 3단계는 상호 의존적입니다. 4와 5는 독립적으로 수행될 수 있지만 5는 3에 약간의 종속성이 있습니다.

이전 버전과의 호환성 #

여기에는 주로 독스트링이 포함되므로 이전 버전과의 호환성에 미치는 영향이 최소화되어야 합니다.

대안 #

아직 논의된 사항이 없습니다.

MEP10: 독스트링 일관성 #

상태 번호

브랜치 및 풀 리퀘스트 #

초록 #

자세한 설명 #

Numpy 독스트링 형식 #

상호 참조 #

서명 재정의 #

복제보다는 연결 #

자동 요약 확장 #

관련 문서로 연결되는 예 #

help()와 브라우저를 사용한 문서화 #

구현 #

이전 버전과의 호환성 #

대안 #