貢献方法¶
Author: Nicolas Rougier
Make sure to read this Documentation style guide [1] as well as these tips, tricks [2] and conventions about documentation content and workflows.
貢献するには？¶
もし講義中に誤字脱字、不明瞭な表現、不器用な表現を見つけたら、ぜひ改善にご協力ください。 簡単なテキスト編集は、 GitHubのフォーク にあるファイルを編集することで行えます。 講義の各htmlページでは、右上の edit ボタンが編集可能なページのソースにリンクしています（プロジェクトのフォークを作成する必要があります）。 ソースを編集し、"Create a new branch for this commit and start a pull request" を選択してください。
まだ取り上げられていないトピックを選び、それを書き上げる！
将来のチュートリアルの範囲について編集者やコントリビューターと議論するために、まずGitHubに新しいissueを作成し、取り上げたいトピックについて説明してください。
次に、各章のディレクトリ（
intro、`advanced、packages）の中に新しいディレクトリを作成し、新しいチュートリアル用のファイルindex.rstを作成します。 新しいファイルを対応する章の目次（index.rst内）に追加してください。
チュートリアルはさまざまな場所で行われ、さまざまな部分が科学計算のためのPythonのコースに統合される可能性があることに留意してください。 そのため、チュートリアルはインタラクティブで、適度な短さ（1～2時間）にしたいものです。
最後になりますが、この資料の目的は、科学的なPythonエコシステムの主な機能を学ぶための簡潔なテキストを提供することです。 参考資料に貢献したい場合は、興味のある特定のパッケージのドキュメントに貢献することをお勧めします。
GitHub を使用する¶
この教材の自分のバージョンを作る最も簡単な方法は、GitHubでフォークし、gitバージョン管理システムを使って自分のフォークを管理することです。 そのためには、GitHubでアカウントを作成し、 このページ の右上にある fork ボタンをクリックするだけです。 gitを使って fork からプルし、変更をプッシュバックすることができます。 もしあなたがその変更点を寄稿して戻したいのであれば、あなたのフォークのページの一番上にあるボタンを使って、 pull request を記入してください。
gitとGitHubを学ぶためのリソースは、全くの初心者向けの https://try.github.io など、オンラインでいくつか入手できます。
どうしても必要な場合を除き、Makefileの改変は控えてください。
簡潔さを保つ: 段落の折りたたみ¶
HTML出力は、授業中にスクリーンに表示するために使用します。目標は、ノートと同じ内容を表示することです。 そのため、本格的な段落や文章ではなく、箇条書きで非常に簡潔に表示する必要があります。 人々が読んだり参照したりできるような、より詳細な議論には tip sphinx ディレクティブを使ってください。 これは折りたたみ可能な段落を作成し、口頭発表の際に隠すことができます:
.. tip::
Here insert a full-blown discussion, that will be collapsible in
the HTML version.
It can span on multiple paragraphs
これは以下のようにレンダリングされます:
Tip
ここに本格的な議論を挿入します、そしてHTML版では折りたたみ式になります。
複数の段落にまたがることができます
図とコード例¶
We do not check figures in the repository.
Any figure must be generated from a python script that needs to be named
plot_xxx.py (xxx can be anything of course) and put into the examples
directory. The generated image will be named from the script name.
これは、画像を入れてコードにリンクする方法です:
.. image:: auto_examples/images/sphx_glr_plot_simple_001.png
:target: auto_examples/plot_simple.html
literal-include ディレクティブを使えば、対応するコードを表示することができます。
"""
A simple example
=================
"""
import numpy as np
import matplotlib.pyplot as plt
X = np.linspace(-np.pi, np.pi, 100)
Y = np.sin(X)
plt.plot(X, Y, linewidth=2)
plt.show()
注釈
Pythonスクリプトを図や例のギャラリーに変換する機能は、 sphinx-gallery パッケージによって提供されます。
Markup を使用する¶
使用すべきマークアップには、主に次の3種類があります。 イタリック体 、 太字 、そして 固定フォント です。 イタリック体 は新しい専門用語を導入する際に、 太字 は強調する際に、そして 固定フォント はソースコードに使用します。
restructuredテキストマークアップでは次のようになります:
when using *object-oriented programming* in Python you **must** use the
``class`` keyword to define your *classes*.
パッケージドキュメントへのリンク¶
科学的Python講義の目的は、様々なパッケージのドキュメントを複製したり置き換えたりすることではありません。できるだけオリジナルのドキュメントにリンクしてください。
APIドキュメントを相互参照するために、私たちは interphinx extension を使うことを好みます。これは :mod:, :class:, :func: というディレクティブを提供し、それぞれモジュール、クラス、関数にクロスリンクします。 例えば、 :func:`numpy.var は numpy.var() のようなリンクを作成します。
チャプター、セクション、サブセクション、パラグラフ¶
段落の粒度を下回ると、文書が読みづらくなる可能性があるので、なるべく避けてください:
=============
Chapter title
=============
Sample content.
Section
=======
Subsection
----------
Paragraph
.........
And some text.
警告¶
注釈
これは注釈です
警告
これは警告です
浮動をクリアする¶
:align: right で配置された図形は浮動します。 それらをフラッシュするには:を使用します:
|clear-floats|