매트플롯립 프로젝트

이 페이지에는 Google Season of Docs에서 승인된 테크니컬 라이팅 프로젝트의 세부정보가 포함되어 있습니다.

프로젝트 요약

오픈소스 조직:
매트플롯립
테크니컬 라이터:
브루노벨트란
프로젝트 이름:
'암시적' 유형의 문서를 표준화하여 기능 검색 가능성 개선
프로젝트 기간:
장기 실행 (5개월)

Project description

동기

지금까지 매트플롯립의 API는 'String-as-enum' '암시적 유형'에 크게 의존했습니다. matlab의 API를 모방하는 것 외에도 이러한 매개변수 문자열을 사용하면 사용자가 기본 플롯 옵션을 전달하기 위해 실제 enum 값을 명시적으로 가져오거나 상세한 접두사로 추가할 필요 없이 의미론적으로 풍부한 값을 매트플롯립 함수에 인수로 전달할 수 있습니다 (즉, plt.plot(x, y, linestyle='solid')는 입력이 더 쉽고 plt.plot(x, y, linestyle=mpl.LineStyle.solid)와 같은 것보다 덜 중복됩니다).

이러한 열거형 열거형 중 다수는 이후 더욱 정교한 기능이 발전했습니다. 예를 들어 linestyle은 이제 문자열 또는 시퀀스의 2튜플이 될 수 있으며 MarkerStyle은 이제 문자열 또는 matplotlib.path.Path일 수 있습니다. 이는 많은 암시적 유형에 해당하지만 MarkerStyle은 올바른 Python 클래스로 업그레이드된 상태로 존재하는 유일한 유형입니다.

이러한 암시적 유형은 그 자체로 클래스가 아니기 때문에, Matplotlib는 Python 클래스에서 제공하는 표준 도구 모음 (예: docstring, __init__ 패턴)을 사용하는 대신 이러한 암시적 유형 (예: 각각 docstring.interpd.update docstring 보간 패턴 및 cbook._check_in_list 검사기 패턴)의 문서 및 유효성 검사를 중앙화하기 위한 자체 솔루션을 배포해야 했습니다.

이러한 솔루션은 효과적이지만 각 암시적 유형을 문서화할 명시적 위치가 없다는 것은 문서를 찾기 어렵고 허용 값으로 구성된 대규모 테이블이 문서 전체에서 반복되며 암시적 유형의 범위에 대한 명시적 구문이 문서에서 완전히 누락되는 경우가 많다는 것을 의미합니다. plt.plot 문서를 참고하세요. 예를 들어 'Notes'에서 matlab과 유사한 형식 문자열 스타일 지정 메서드에 관한 설명에서 linestyle, color, markers 옵션을 언급합니다. 이 세 가지 값을 전달하는 방법은 여러 가지가 있지만, 대부분의 사용자는 관련 튜토리얼 중 하나를 우연히 알게 될 때까지 이러한 옵션에 어떤 값을 사용할 수 있는지 알 수 있는 유일한 방법입니다. Line2D 속성 표는 플롯을 제어하는 데 사용할 수 있는 옵션을 독자에게 보여주기 위해 포함됩니다. 그러나 linestyle 항목은 가능한 입력이 설명된 Line2D.set_linestyle (클릭 2회 필요)에 원활하게 연결되지만 color 및 markers 항목은 그렇지 않습니다. color는 단순히 Line2D.set_color에 연결되므로 허용되는 입력의 종류에 관한 직관을 제공하지 못합니다.

문제를 일으키는 개별 docstring을 정리하는 것만으로도 이 문제를 해결할 수 있다고 주장할 수 있지만 안타깝게도 이 문제는 그보다 훨씬 시스템적입니다. 중앙에서 문서를 찾을 수 없으면 이러한 각 암시적 유형이 사용되는 모든 위치에서 점점 더 상세한 문서 사본이 점점 늘어나기 때문에 초보 사용자가 필요한 매개변수를 간단히 찾기가 특히 더 어려워집니다. 하지만 사용자가 문서 전체에서 위키 다이빙 스타일 순회 또는 StackOverflow 예제의 단편을 통해 각 암시적 유형의 멘탈 모델을 천천히 병합하도록 하는 현재 시스템도 지속 가능하지 않습니다.

최종 목표

암시적 유형의 모든 언급은 유형에 사용할 수 있는 모든 가능한 값을 가장 단순하고 일반적인 값부터 가장 고급 또는 복잡한 복잡한 순으로 나열하여 설명하는 단일 페이지로 연결되는 것이 이상적입니다. 가능한 모든 입력 유형을 특정 매개변수에 단편적으로 열거하기 위해 최상위 API 문서의 중요한 시각적 공간을 사용하는 대신, 같은 공간을 사용하여 매개변수가 제어해야 하는 추상화를 그래프로 나타내는 간단한 설명을 제공할 수 있습니다.

linestyle의 예를 다시 사용하기 위해 LineCollection 문서에서 원하는 내용은 다음과 같습니다.

  1. 허용되는 입력에 관한 전체 문서 링크 (Line2D.set_linestyle 및 라인 스타일 튜토리얼에 있는 항목 조합)
  2. 매개변수로 수행할 작업에 대한 간단한 단어 설명입니다. Matplotlib 고급 사용자의 경우 이는 매개변수 이름에서 확인할 수 있지만 신규 사용자에게는 그렇지 않아도 됩니다.

실제 LineCollection 문서에서 이 내용은 python """""" linestyles: `LineStyle` or list thereof, default: :rc:`lines.linestyle` ('-') A description of whether the stroke used to draw each line in the collection is dashed, dotted or solid, or some combination thereof. """"""일 뿐입니다. 여기서 LineStyle 유형 참조는 Sphinx에 의해 결정되어 매트플롯립이 선 스타일을 처리하는 방법에 관한 신뢰할 수 있는 온전한 문서 집합을 가리킵니다.

이점

이 접근 방식의 몇 가지 강력한 특징은

  1. 일반 텍스트에서 각 함수가 할 수 있는 작업을 완벽히 설명합니다 (클릭 없이 표시됨).
  2. 기본 옵션을 표시합니다 (클릭 0회). 기본 옵션을 보는 것만으로도 재방문 사용자의 기억을 되살릴 수 있습니다.
  3. 탐색할 때 클릭 한 번으로 쉽게 사용할 수 있는 매개변수의 '가장 일반적'과 '가장 쉬운' 옵션을 자세히 설명합니다.
  4. 더 강력한 기능과 입력 방법을 찾는 과정을 '아래로 스크롤'하면 더 많은 고급 옵션을 확인할 수 있습니다 (클릭 한 번으로 가능).
  5. 최상위 'API' 문서를 관련 '튜토리얼'에 연결하기 위한 중앙 집중식 전략을 제공합니다.
  6. 각 매개변수에 대해 가능한 많은 옵션을 스캔하면 개별 docstring이 다루기 힘들어지는 API-doc-explosion을 피합니다.

현재 문서에 비해 이 접근 방식의 다른 이점은 다음과 같습니다.

  1. 문서가 중앙 집중화되므로 오래될 가능성이 낮습니다.
  2. 현재 코드를 읽어 학습해야 하는 여러 매트플롯립의 '암시적 표준' (예: '바인드' 대 '익스텐트'의 정의)의 표준화.
  3. 이 프로세스에서는 GitHub Issue Tracker를 통해 더 쉽게 추적할 수 있는 방식으로 API 일관성 문제를 강조 표시하여 API 개선 프로세스에 도움을 줍니다.
  4. 파싱해야 하는 텍스트의 양이 크게 줄어들어 문서 빌드 시간이 빨라집니다.

구현

위에서 설명한 개선사항을 실현하려면 두 가지 주요 노력이 필요하며, 이를 위해서는 전담 테크니컬 라이터가 매우 중요합니다. 첫 번째는 암시적 유형당 하나의 중앙 집중식 ''튜토리얼' 페이지를 만드는 것입니다. 이를 위해서는 핵심 개발자팀과 협력하여 사용자에게 유용한 문서의 암시적 유형 목록을 식별해야 합니다 (일반적으로 이러한 유형의 암시적 유형 목록은 일반적으로 이해하기 어려운 튜토리얼에서만 찾을 수 있는 Google 라이브러리의 강력하고 숨겨진 기능을 포함하고 있기 때문). 그런 다음 암시적 유형마다 다양한 관련 튜토리얼, API 문서, 예시 페이지를 특정 유형이 참조되는 모든 위치에 연결할 수 있는 신뢰할 수 있는 단일 문서 소스로 합성하겠습니다.

특정 암시적 유형에 관한 중앙 집중식 문서가 완성되면 두 번째 주요 작업이 시작됩니다. 기존 API 문서를 새 문서 링크로 대체하고, Python의 기본 제공 help() 유틸리티를 사용하는 사용자와 온라인으로 문서를 탐색하는 사용자 모두 실제로 새 문서를 최대한 쉽게 사용할 수 있도록 하는 데 중점을 둡니다.

여기서 제안된 문서의 정확한 형식은 이 프로젝트가 진행됨에 따라 변경될 수 있지만, 저는 Matplotlib 핵심 팀과 주간 '개발자 호출' 중에 협력하여 여기에서 제안된 전략이 이러한 ''암시적 유형'을 문서화하는 데 있어 가장 편리하고 유용하며 기술적으로 처리 가능한 접근 방식이라는 합의를 이루었습니다(이러한 'MD 해킹'에 관한 참고사항). 각 암시적 유형에 관한 중앙 집중식 문서를 만드는 초기 단계에 기존의 '튜토리얼' 인프라를 사용하여 새 공개 클래스를 만들지 않고도 다음과 같이 이러한 페이지를 쉽게 참조할 수 있습니다 (예: LineCollection 문서 사용).

""""""
linestyles: LineStyle or list thereof, default: :rc:`lines.linestyle` ('-')
    A description of whether the stroke used to draw each line in the collection
    is dashed, dotted or solid, or some combination thereof. For a full
    description of possible LineStyle's, see :doc:`tutorials/types/linestyle`.
""""""

앞으로는 핵심 개발자팀이 새로운 '유형' 문서를 완전한 Python 클래스에 통합하기 위한 최상의 장기 전략에 관해 합의하면 이러한 참조의 철자를 쉽게 변경할 수 있습니다. 예를 들어 Matplotlib 개선 제안 30에서 제안한 바 있습니다.

마지막으로 이번 Google Docs 시즌 중에 문서화할 것을 제안하는 암시적 유형의 예비 목록은 다음과 같습니다.

  1. capstyle
  2. joinstyle
  3. bounds
  4. extents
  5. linestyle
  6. colors/lists of colors
  7. colornorm/colormap
  8. tick formatters

이 문서의 현재 버전은 Google 담화에서 확인할 수 있습니다.