매트플롯립 프로젝트

이 페이지에는 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 문서를 참고하세요. '메모''에서 matlab과 같은 형식 문자열 스타일 지정 메서드에 관한 설명에서 linestyle, color, markers 옵션을 언급합니다. 이러한 세 가지 값을 전달하는 방법은 여기서 찾을 수 있는 것보다 더 많지만, 대부분의 사용자는 관련 튜토리얼 중 하나를 우연히 보게 될 때까지 이러한 옵션에 어떤 값을 사용할 수 있는지 알 수 있는 유일한 방법입니다. 플롯을 제어할 수 있는 옵션이 무엇인지 독자에게 보여주기 위해 Line2D 속성 테이블이 포함됩니다. 그러나 가능한 입력이 설명된 경우 linestyle 항목은 Line2D.set_linestyle (클릭 두 번 필요)에 원활하게 연결되지만 color 및 markers 항목은 그렇지 않습니다. color는 단순히 Line2D.set_color에 연결되므로 어떤 종류의 입력이 허용되는지 직관을 제공하지 못합니다.

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

최종 목표

이상적으로는 암시적 유형에 관한 언급은 유형이 취할 수 있는 모든 가능한 값을 설명하는 단일 페이지에 연결해야 합니다(가장 단순하고 일반적인 값부터 가장 고급 또는 난해한 순서로 정렬). 최상위 API 문서에서 유용한 시각적 공간을 사용하여 가능한 모든 입력 유형을 특정 매개변수에 대해 부분적으로 열거하는 대신, 동일한 공간을 사용하여 매개변수 추상화가 제어되어야 하는 것이 무엇인지에 관해 간단명료한 설명을 제공할 수 있습니다.

linestyle의 예를 다시 사용하기 위해 LineCollection 문서에 필요한 것은 다음과 같습니다.

  1. 허용되는 입력에 관한 전체 문서 링크 (Line2D.set_linestyle 및 선 스타일 튜토리얼에 있는 항목 조합)
  2. 매개변수를 통해 달성해야 하는 작업에 관한 일반적인 설명입니다. 매트플롯립 고급 사용자는 매개변수 이름에서 이를 알 수 있지만 신규 사용자에게는 그럴 필요가 없습니다.

실제 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. 기본 옵션을 표시합니다 (클릭 없이 표시). 기본 옵션을 보는 것만으로도 재사용자의 기억을 덜어낼 수 있습니다.
  3. 탐색할 때 (클릭 한 번으로) 쉽게 사용할 수 있는 매개변수의 ''가장 일반적인'' 및 ''가장 쉬운'' 옵션에 대한 자세한 설명을 작성합니다.
  4. 더욱 강력한 기능과 입력 방법을 찾는 과정을 '아래로 스크롤'하는 것만큼 간단하게 만들어 더 많은 고급 옵션을 확인할 수 있습니다 (클릭 한 번으로 계속).
  5. 최상위 'API' 문서를 관련 '튜토리얼'에 연결하기 위한 중앙 집중식 전략을 제공합니다.
  6. 각 매개변수에 대해 가능한 많은 옵션을 스캔하면 개별 docstring이 다루기 어려워지는 API-doc-explosion을 피하세요.

현재 문서와 비교할 때 이 접근 방식의 다른 이점은 다음과 같습니다.

  1. 중앙 집중화로 인해 문서가 비활성 상태가 될 가능성이 낮습니다.
  2. 현재 코드를 읽어 학습해야 하는 matplotlib의 ''암시적 표준' (예: '경계' 대 '범위'의 정의) 대다수의 표준화.
  3. 이 프로세스에서는 API 일관성 관련 문제를 GitHub Issue Tracker를 통해 더 쉽게 추적할 수 있는 방식으로 강조 표시하여 API 개선 프로세스를 지원합니다.
  4. 파싱해야 할 텍스트 양이 크게 감소하여 문서 빌드 시간이 단축됩니다.

구현

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

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

여기서 제안된 문서의 정확한 형식은 이 프로젝트가 발전함에 따라 변경될 수 있지만, 저는 매주 진행되는 ''개발 통화'' 중에 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 문서 시즌 동안 문서화하는 것을 제안하는 암시적 유형의 예비 목록은 다음과 같습니다.

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

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