matplotlib プロジェクト

このページには、Google Season of Docs で承認されたテクニカル ライティング プロジェクトの詳細が掲載されています。

プロジェクトの概要

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

プロジェクトの説明

目的

これまで、matplotlib の API は、列挙型としての文字列の「暗黙の型」に大きく依存してきました。これらのパラメータ文字列は、matlab の API を模倣するだけでなく、基本的なプロット オプションを渡すために実際の列挙値を明示的にインポートしたり、冗長な接頭辞を付けたりしなくても、意味のある値を matplotlib 関数に引数として渡すことができます（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 や validate-at-__init__ パターンなど）を使用する代わりに、これらの暗黙的な型のドキュメントと検証を集中管理するための独自のソリューションをロールアウトする必要がありました。docstring.interpd.updatecbook._check_in_list

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

これは、問題の原因となっている個々のドキュメントを整理するだけで解決できるという意見もありますが、残念ながら、この問題はもっと根本的なものです。ドキュメントを探すための一元的な場所がないと、これらの暗黙的な型が使用される場所ごとに、冗長なドキュメントのコピーがどんどん増え、初心者のユーザーが必要なパラメータを簡単に見つけることが難しくなります。ただし、ドキュメント全体の Wiki ダイビング スタイルのトラバーサル、または 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 によって解決され、Matplotlib による線画の処理方法に関する信頼できる完全なドキュメント セットを参照しています。

利点

このアプローチの強力な機能には次のようなものがあります。

  1. 各関数の機能を平文で（クリックなしで）完全に把握できるようにする。
  2. デフォルト オプションを表示する（クリックなし）。多くの場合、デフォルト オプションが表示されるだけで、リピーターの記憶が呼び起こされます。
  3. ブラウジング時に簡単に利用できる（ワンクリックで利用できる）パラメータの「最も一般的な」オプションと「最も簡単な」オプションをすべて説明します。
  4. より高度な機能や入力方法を見つけるプロセスを、（1 回のクリックで）「下にスクロール」するだけで簡単にできるようにします。
  5. 最上位の「API」ドキュメントを関連する「チュートリアル」にリンクするための一元化された戦略を提供する。
  6. 各パラメータに可能な多くのオプションをスキャンして個々のドキュメントを扱いにくい状態になる、API ドキュメントの爆発を回避します。

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

  1. 一元化されているため、ドキュメントが古くなる可能性は低くなります。
  2. matplotlib の多くの「暗黙的な標準」（「境界」と「範囲」の違いなど）を標準化。現在、コードを読んで学習する必要があります。
  3. このプロセスでは、GitHub の問題トラッカーでより簡単に追跡できる方法で、API の整合性に関する問題がハイライト表示され、API の改善プロセスに役立ちます。
  4. 解析が必要なテキストの量が大幅に減少するため、ドキュメントのビルド時間が短縮されます。

実装

上記の改善には、専任の技術ライターが不可欠な 2 つの大きな作業が必要になります。1 つ目は、暗黙的な型ごとに 1 つの一元化された「チュートリアル」ページを作成することです。これを行うには、コア デベロッパー チームと連携して、ユーザーにとって有益なドキュメントが作成できる暗黙的な型の具体的なリストを特定する必要があります（通常、ライブラリの強力な隠し機能が含まれているため、ドキュメントは現在、見つけにくいチュートリアルにのみ記載されています）。暗黙的な型ごとに、さまざまな関連チュートリアル、API ドキュメント、サンプルページを、特定の型が参照されている任意の場所にリンクできる信頼できる単一のドキュメントに統合します。

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

ここで提案されているドキュメントの正確な形式は、このプロジェクトの進展に伴って変更される可能性がありますが、私は 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 でご覧いただけます。