matplotlib プロジェクト

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

プロジェクトの概要

オープンソースの組織:
Matplotlib
テクニカル ライター:
brunobeltran
プロジェクト名:
「暗黙的」な型のドキュメントの標準化による機能の見つけやすさの改善
プロジェクトの期間:
長時間（5 か月）

プロジェクトの説明

目的

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

以降、これらの文字列としての列挙型の暗黙的な型の多くは、より洗練された機能に進化しています。たとえば、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 つの値を渡す方法は、ヒントでも紹介されている以外にも多数ありますが、多くのユーザーにとって、これらのオプションに指定できる値については、関連するチュートリアルの 1 つに遭遇するまでは、これが唯一の情報源となります。プロットを制御するためのオプションを示すために、Line2D 属性の表も記載されています。ただし、可能な入力が記述されている場合、linestyle エントリは Line2D.set_linestyle にリンクします（2 回のクリックが必要です）。color エントリと markers エントリはリンクされません。color は単純に Line2D.set_color にリンクしていますが、どのような入力が許可されるかについて直感的に理解できません。

これは、問題の原因となっている個々の docstring を整理するだけで解決できますが、残念ながら問題はそれよりもはるかに体系的なものです。ドキュメントを 1 か所で見つけられる場所がなければ、これらの暗黙的な型が使用されるあらゆる場所で繰り返される、次第に冗長なドキュメントのコピーが増えることになり、初心者にとっては必要なパラメータを簡単に見つけることが特に難しくなります。しかし、ドキュメント全体を通してウィキダイビング スタイルのトラバーサルによって各暗黙的タイプのメンタルモデルを徐々につなぎ合わせる必要がある現在のシステム、または 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 ドキュメントの爆発的な増大を避ける。各パラメータに対して考えられる多くのオプションをスキャンすると、個々の docstring が扱いにくくなる。

現行のドキュメントと比較した場合の、このアプローチの他の利点は次のとおりです。

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

実装

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

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

ここで提案するドキュメントの正確な形式は、このプロジェクトの進展にともなって変更される可能性がありますが、私は、毎週の「開発コール」で Matplotlib コアチームと協力し、ここで提案する戦略が最も便利で有用で、技術的に扱いやすいアプローチであるというコンセンサスを確立しました（これらの「暗黙的な型」の文書化に関するメモは公開されています）。暗黙的なタイプごとに一元化されたドキュメントを作成する際の初期段階では、既存の「tutorials」インフラストラクチャを使用します。これにより、新しいパブリック クラスを作成しなくても、次のようにこれらのページを簡単に参照できます（ここでも 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 拡張提案 30 で私が提案したように、新しい「タイプ」ドキュメントを正しい Python クラスに組み込むための最適な長期戦略についてコア デベロッパー チームが合意して、これらの参照のスペルを簡単に変更できます。

最後に、この Google ドキュメント シーズンに私が提案する暗黙的な型のリストは次のとおりです。

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

このドキュメントの実版は Discourse で入手できます。