matplotlib プロジェクト

このページには、Google シーズンの Google ドキュメントで承認されたテクニカル ライティング プロジェクトの詳細が記載されています。

プロジェクトの概要

オープンソースの組織:
Matplotlib
テクニカル ライター:
brunobeltran
プロジェクト名:
「暗黙的」タイプのドキュメントを標準化することで、機能を見つけやすくする
プロジェクトの期間:
長時間実行（5 か月）

プロジェクトの説明

目的

歴史的に、matplotlib の API は string-as-enum の「implicit types」に大きく依存していました。matlab の API を模倣するだけでなく、これらのパラメータ文字列を使用すると、基本的なプロット オプションを渡すためだけに、実際の列挙値を明示的にインポートしたり、冗長な値にしたりすることなく、意味的に豊富な値を matplotlib 関数に引数として渡すことができます（つまり、plt.plot(x, y, linestyle='solid') は入力が簡単で、plt.plot(x, y, linestyle=mpl.LineStyle.solid) のようなものよりも冗長です）。

その後、これらの string-as-enum の暗黙的な型の多くは、より洗練された機能に進化しました。たとえば、linestyle は文字列または 2 タプルのシーケンスになり、MarkerStyle は文字列または matplotlib.path.Path のいずれかになります。これは多くの暗黙的な型に当てはまりますが、私の知る限りでは、適切な Python クラスにアップグレードされたというステータスを持つのは MarkerStyle だけです。

これらの暗黙的な型はそれ自体はクラスではないため、Matplotlib はこれまで、これらの暗黙的な型のドキュメントと検証を一元化するための独自のソリューション（それぞれ docstring.interpd.update docstring 補間パターンと cbook._check_in_list バリデータ パターンなど）を用意する必要がありました。__init__

これらのソリューションはうまく機能しましたが、各暗黙的な型を文書化する明示的な場所がないため、ドキュメントを見つけるのが難しいことが多く、許可される値の大きな表がドキュメント全体で繰り返されています。また、暗黙的型のスコープの明示的なステートメントがドキュメントから完全に欠落していることも少なくありません。たとえば、plt.plot ドキュメントを見てみましょう。"Notes" では、matlab のような形式文字列のスタイル設定メソッドの説明に、linestyle、color、markers オプションが記載されています。これら 3 つの値を渡す方法は、ヒントで示されている方法以外にも多数ありますが、多くのユーザーにとっては、関連するチュートリアルのいずれかに遭遇するまで、これらのオプションに使用可能な値を理解する唯一の情報源となります。プロットを制御するためのオプションを読者に示すため、Line2D 属性の表も記載しています。ただし、linestyle エントリは、可能な入力が記述されている Line2D.set_linestyle へのリンク（クリックは 2 回必要）には適していますが、color エントリと markers エントリは適切にリンクしていません。color は単に Line2D.set_color にリンクしており、どのような種類の入力が許可されているかについて直感的に説明できません。

これは、問題の原因となっている個々の docstring を整理するだけで解決できる可能性があるものの、残念ながら問題はそれよりもはるかに体系的なものです。ドキュメントを見つけるための一元化された場所がなければ、これらの暗黙的なタイプが使用されるあらゆる場所で、ますます冗長なドキュメントのコピーがますます増えてしまい、初心者が必要なパラメータを簡単に見つけることが特に難しくなります。ただし、ドキュメント全体にわたって Wiki ダイビング スタイルのトラバーサルによって各暗黙的タイプのメンタルモデルを徐々につなぎ合わせる、または StackOverflow の例から断片的にするといった現在のシステムも、持続可能ではありません。

最終目標

暗黙的な型については、その型が取り得るすべての値を 1 つのページにリンクして、最もシンプルで一般的なものから最も高度なもの、または難解なものの順に記載するのが理想的です。トップレベルの 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. 各パラメータに対して多くの可能なオプションをスキャンすると、個々の docstring が扱いづらくなる、API ドキュメントの爆発を避ける。

現在のドキュメントと比較した、このアプローチには他にも次のようなメリットがあります。

  1. 一元化によりドキュメントが古くなる可能性が低くなります。
  2. matplotlib の多くの「暗黙的な標準」（「境界」と「エクステント」）の正規化。現在、コードを読むことによって学習する必要があります。
  3. このプロセスにより、API の整合性に関する問題が GitHub Issue Tracker でより簡単に追跡できるようになり、API の改善プロセスに役立ちます。
  4. 解析が必要なテキストの量が大幅に減少するため、ドキュメント ビルド時間が短縮されます。

実装

上記の改善を行うには、専任のテクニカル ライターが非常に重要となる 2 つの主要な取り組みが必要です。1 つ目は、暗黙的なタイプごとに一元化された「チュートリアル」ページを 1 つ作成する方法です。そのためには、コア デベロッパー チームと協力して、ユーザーにとって価値のあるドキュメントを含む暗黙的な型の具体的なリストを特定する必要があります（通常は、ライブラリの強力な隠し機能が含まれており、そのドキュメントが現在、行き詰まりにくいチュートリアル内でしか見つかっていないためです）。暗黙的なタイプごとに、関連するさまざまなチュートリアル、API ドキュメント、サンプルページを 1 つの信頼できるドキュメント ソースにまとめ、その特定のタイプが参照される場所にリンクできます。

特定の暗黙的なタイプについて一元化されたドキュメントが完成すると、2 つ目の大きな作業が始まります。既存の API ドキュメントを新しいドキュメントへのリンクに置き換えます。Python の組み込み help() ユーティリティを使用しているユーザーと、オンラインでドキュメントを閲覧しているユーザーの両方にとって、この新しいドキュメントをできるだけ簡単に使用できるようにすることを目指します。

ここで提案するドキュメントの正確な形式は、このプロジェクトの進展に伴い変わる可能性がありますが、私は、Matplotlib コアチームと週 1 回の「開発コール」で協力して、「暗黙的なタイプ」を文書化するための最も便利で有用で、技術的に扱いやすいアプローチであるというコンセンサスを得ました（これらのハッキングに関する注記があります）。暗黙的なタイプごとに一元化されたドキュメントを作成する初期段階で、既存の「チュートリアル」インフラストラクチャを使用します。これにより、新しいパブリック クラスを作成する必要なく、次のようにページを簡単に参照できます（ここでも 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`.
""""""

今後は、Matplotlib Enhancement Proposal 30 で提案したように、新しい「タイプ」ドキュメントを真正な Python クラスに組み込むための最適な長期戦略にコア デベロッパー チームが合意したら、これらのリファレンスのスペルを簡単に変更できます。

最後に、この Google シーズンのドキュメントで私が提案する暗黙のタイプの予備リストを次に示します。

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

このドキュメントのライブ版は、ディスカッションでご覧いただけます。