MEP12: ギャラリーとサンプルの改善#
ステータス番号
進捗
1.3 で追加された初期の変更。ギャラリーの変換が進行中です。2015 年 9 月 29 日 - 最後のpylab_exampleswherepylabがインポートされ、使用するように変換されましmatplotlib.pyplotたnumpy。
ブランチとプルリクエスト#
#1623、#1924、#2181
PR #2474 は、クリーンアップされて適切なセクションに移動された 1 つの例を示しています。
アブストラクト#
matplotlib プロット ギャラリーを再編成すると、ギャラリーのナビゲーションが大幅に簡素化されます。さらに、明確にするために、例をクリーンアップして単純化する必要があります。
詳細な説明#
matplotlib ギャラリーは最近、例をセクションに分割するように設定されました。その PR [ 1 ]で説明されているように、現在の例のセクション ( api、pylab_examples) はユーザーにとってあまり役に立ちません。ギャラリーの新しいセクションは、ユーザーが関連する例を見つけるのに役立ちます。
これらのセクションは、例のクリーンアップもガイドします。最初は、現在のすべての例が残り、現在のディレクトリの下にリストされます。時間が経つにつれて、これらの例はクリーンアップされ、新しいセクションの 1 つに移動される可能性があります。
このプロセスにより、ユーザーはクリーンアップが必要な例を簡単に特定できます。つまり、apiおよびpylab_examples
ディレクトリ内のすべて。
実装#
新しいギャラリー セクションを作成します。[終わり]
例をクリーンアップし、それらを新しいギャラリー セクションに移動します (多くの PR の過程で、多くのユーザー/開発者の助けを借りて)。[進行中]
ギャラリー セクション#
セクションの命名は重要であり、クリーンアップ作業の指針となります。現在のセクションは次のとおりです。
線、棒、およびマーカー (多かれ少なかれ 1D データ)
シェイプとコレクション
統計プロット
画像、等高線、およびフィールド
円グラフと極グラフ: 丸いもの
色
テキスト、ラベル、注釈
ダニとトゲ
サブプロット、座標軸、および Figure
特殊プロット (サンキー、レーダー、竜巻など)
ショーケース (出版品質にするための調整を加えたプロット)
ツールボックスの個別のセクション (既に存在します: 'mplot3d'、'axes_grid'、'units'、'widgets')
これらの名前は確かに議論の余地があります。これらのセクションが大きくなるにつれて、それらを再評価し、必要に応じて分割する必要があります。
クリーンアップのガイドライン#
apiギャラリーのおよびセクションにある現在の例は、pylab_examplesクリーンアップされるまでこれらのディレクトリに残ります。クリーンアップ後、上記の新しいギャラリー セクションのいずれかに移動されます。「クリーンアップ」には以下が含まれます。
sphinx-gallery docstrings : 例の上部に、次のようにフォーマットされた例のタイトルと説明:
""" =============================== Colormaps alter your perception =============================== Here I plot the function .. math:: f(x, y) = \sin(x) + \cos(y) with different colormaps. Look at how colormaps alter your perception! """
コメントアウトされたコードは削除する必要があります。
シバン行を削除します。例:
#!/usr/bin/env パイソン
一貫性のあるインポートを使用します。特に：
numpy を np としてインポート
matplotlib.pyplot を plt としてインポート
これらのモジュールから特定の関数をインポートすることは避けてください (例: )
from numpy import sin各例は、特定の機能に焦点を当てる必要があります (
showcaseより「洗練された」プロットを示す例を除く)。その機能に関係のない微調整は削除する必要があります。f7b2217、 e57b5fc、および1458aa8を参照してください 。
の使用pylabについては、ギャラリーの例ではなく、専用のヘルプ ページで説明/説明する必要があります。
注:既存の例を移動する場合は、その例への参照を検索する必要があります。たとえば、
axes.pyおよびの API ドキュメントでは、pyplot.pyこれらの例を使用してプロットを生成できます。お気に入りの検索ツール (grep、ack、grin、pssなど) を使用して、matplotlib パッケージを検索します。2dc9a46
およびaa6b410を参照
追加の提案#
使用されているメソッド/オブジェクトの例と API ドキュメント間のリンク (双方向) を提供します。(issue #2222 )
plt.subplotsより優先して (末尾の「s」に注意) を 使用しplt.subplotます。目的を明確にするために例の名前を変更します。たとえば、 の最も基本的なデモは で
imshowありimshow_demo.py、異なる補間設定を示すデモはimshow_demo_interpolation.py( notimshow_demo2.py) です。新しいものを示さない例を削除します。
一部の例では、単体テスト用の難解な機能を実行します。
unitこれらの調整は、ギャラリーから、パッケージのルート ディレクトリにあるディレクトリ内の例に移動する必要が あります。プロット タイトルを追加して、例の意図を明確にします。bd2b13cを参照
下位互換性#
各 Matplotlib バージョンの Web サイトには簡単にアクセスできるため、古い例を参照したいユーザーは引き続き参照できます。