매트플롯립 프로젝트

이 페이지에는 Google Season of Docs에 선정된 기술 문서 프로젝트의 세부정보가 포함되어 있습니다.

프로젝트 요약

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

Project description

동기

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

이러한 enum으로서의 문자열 암시적 유형의 대부분은 이후 더 정교한 기능으로 발전했습니다. 예를 들어 linestyle는 이제 문자열 또는 2튜플의 시퀀스가 될 수 있으며, MarkerStyle은 이제 문자열 또는 matplotlib.path.Path가 될 수 있습니다. 이는 많은 암시적 유형에 적용되지만, MarkerStyle은 적절한 Python 클래스로 업그레이드된 상태인 유일한 유형입니다 (제 지식으로는).

이러한 암시적 유형은 그 자체로 클래스가 아니므로 매트플롯립은 역사적으로 이러한 암시적 유형 (예: docstring.interpd.update docstring 보간 패턴 및 cbook._check_in_list 유효성 검사 패턴)을 중앙 집중화하고 검증하기 위한 자체 솔루션을 각 Python 클래스 (예: docstrings, validate-at-__init__)에서 제공하는 표준 도구 모음을 사용하는 대신 사용해야 했습니다.

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

문제를 일으키는 개별 문서 문구를 정리하기만 하면 해결할 수 있다고 주장할 수 있지만 안타깝게도 이 문제는 그보다 훨씬 더 체계적인 문제입니다. 문서를 찾을 수 있는 중앙 집중식 장소가 없으면 이러한 암시적 유형이 각각 사용되는 모든 곳에서 점점 더 상세한 문서의 사본이 점점 더 많이 반복될 뿐입니다. 따라서 초보 사용자가 필요한 매개변수를 찾기가 특히 더 어려워집니다. 하지만 사용자가 문서 전체를 탐색하는 위키 다이빙 스타일 또는 StackOverflow 예시에서 부분적으로 각 암시적 유형의 정신 모델을 천천히 조합하도록 강요하는 현재 시스템도 지속 가능하지 않습니다.

최종 목표

암시적 유형에 대한 언급은 유형이 취할 수 있는 모든 값을 가장 간단하고 일반적인 순서에서 가장 고급 또는 난해한 순서로 설명하는 단일 페이지로 연결하는 것이 좋습니다. 최상위 API 문서에서 소중한 시각적 공간을 사용하여 특정 매개변수에 가능한 모든 입력 유형을 나열하는 대신 동일한 공간을 사용하여 매개변수가 제어하려는 표시 추상화에 관한 간단한 설명을 제공할 수 있습니다.

linestyle 예시를 다시 사용하려면 LineCollection 문서에 다음이 포함되어야 합니다.

  1. 허용되는 입력 (Line2D.set_linestyle 및 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에 의해 확인되어 Matplotlib에서 선 스타일을 처리하는 방법에 관한 단일의 공신력 있는 완전한 문서 집합을 가리킵니다.

이점

이 접근 방식의 몇 가지 강력한 특징은 다음과 같습니다.

  1. 각 함수가 할 수 있는 작업의 전체 범위를 일반 텍스트로 명확하게 표시합니다 (클릭이 필요하지 않음).
  2. 기본 옵션 표시 (클릭 없이) 기본 옵션을 표시하는 것만으로도 재방문자의 기억을 되살릴 수 있습니다.
  3. 탐색 시 클릭 한 번으로 쉽게 사용할 수 있는 매개변수의 '가장 일반적인' 및 '가장 쉬운' 옵션을 완전히 설명합니다.
  4. 더 강력한 기능과 입력 방법을 찾는 과정을 '스크롤'하는 것처럼 간편하게 만들고 고급 옵션을 클릭 한 번으로 확인할 수 있습니다.
  5. 최상위 ''API' 문서를 관련 ''튜토리얼'에 연결하기 위한 중앙 집중식 전략을 제공합니다.
  6. 각 매개변수에 가능한 여러 옵션을 스캔하여 개별 문서 문자열을 다루기 어렵게 만드는 API 문서 폭발을 피하세요.

이 접근 방식의 다른 이점은 다음과 같습니다.

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

구현

위에 설명된 개선사항을 구현하려면 두 가지 주요 작업이 필요하며 이때 전담 기술 작가가 큰 도움이 됩니다. 첫 번째는 암시적 유형별로 중앙 집중식 '튜토리얼' 페이지를 하나 만드는 것입니다. 이를 위해서는 핵심 개발자팀과 협력하여 문서가 사용자에게 유용한 암시적 유형의 구체적인 목록을 파악해야 합니다. 일반적으로 이러한 유형에는 문서가 현재 찾기 어려운 튜토리얼에만 있는 라이브러리의 강력한 숨겨진 기능이 포함되어 있기 때문입니다. 그런 다음 각 암시적 유형에 대해 다양한 관련 튜토리얼, API 문서, 예시 페이지를 특정 유형이 참조되는 모든 위치에 연결할 수 있는 단일 권위 있는 문서 소스로 종합합니다.

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

여기에 제안된 문서의 정확한 형식은 이 프로젝트가 진행됨에 따라 변경될 수 있지만, 저는 Matplotlib 핵심팀과 함께 주간 '개발자 통화'에서 이러한 '암시적 유형'을 문서화하기 시작하는 데 가장 편리하고 유용하며 기술적으로 다루기 쉬운 접근 방식은 여기에 제안된 전략이라는 합의를 도출했습니다(이 통화에 관한 메모는 hackmd에서 확인할 수 있음). 각 암시적 유형에 관한 중앙 집중식 문서를 만드는 초기 단계에는 기존의 '튜토리얼' 인프라를 사용하겠습니다. 그러면 새 공개 클래스를 만들지 않고도 다음과 같이 이러한 페이지를 쉽게 참조할 수 있습니다 (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

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