Improving documentation
Juliaのドキュメントに貢献すると、その内容をMIT Licenseのライセンスで公開することに同意したものとみなされます。
Juliaのドキュメントのソースファイルはdoc/ディレクトリにあり、すべてのdocstringはbase/にあります。ほかのファイルと同様、これらもgitを使って変更できます。ドキュメントのビルドには、Markdown構文を使うDocumenter.jlを使用します。HTMLドキュメントは、Juliaのルートディレクトリで次のコマンドを実行するとローカルでビルドできます。
make docsこのコマンドは、Juliaのシステムイメージを再ビルドし、ドキュメントのビルドに必要なパッケージ依存関係をインストールまたは更新した後、HTMLドキュメントをビルドして、生成されたファイルをdoc/_build/html/に配置します。
注
Juliaのドキュメントを変更した場合は、プルリクエストを作成する前に
make docsを実行し、変更が有効でエラーを引き起こさないことを確認することをおすすめします。
以下では、最も一般的な3種類のドキュメント変更と、それぞれに必要な手順を説明します。なお、以下の手順ではDocumenter.jlが提供するすべての機能を網羅しているわけではありません。ここに記載されていない内容については、Documenter's documentationを参照してください。
Modifying files in doc/src/
Juliaマニュアルのソーステキストの大部分はdoc/src/にあります。既存ファイルのテキストを更新または追加するには、次の手順に従います。
- 該当する
.mdファイルのテキストを更新する。 - ルートディレクトリで
make docsを実行する。 doc/_build/html/の出力を確認し、変更が正しいことを確かめる。- 変更をコミットし、プルリクエストを作成する。
注
変更を加えた場合でも、
doc/_build/の内容をコミットする必要はありません。
ファイルを更新するのではなく、doc/src/に新しいファイルを追加する場合は、上記の手順1を次の手順に置き換えます。
- 適切な
doc/src/サブディレクトリにファイルを追加し、doc/make.jl内のPAGESベクターにもファイルパスを追加する。
Modifying an existing docstring in base/
docstringは、対象となるメソッドや型の直前にインラインで記述されています。HTMLファイルで各docstringの下に表示されるsourceリンクをクリックすると、その場所を確認できます。既存のdocstringを変更する手順は次のとおりです。
base/でdocstringを見つける。- docstringのテキストを更新する。
- ルートディレクトリで
make docsを実行する。 doc/_build/html/の出力を確認し、変更が正しいことを確かめる。- 変更をコミットし、プルリクエストを作成する。
Adding a new docstring to base/
新しいdocstringを追加するには、次の手順に従います。
docstringの対象として最も適切な定義を
base/で見つける。定義の直前にdocstringを追加する。
docstringを表示したい
doc/src/stdlib/ファイルのいずれかで、適切な@docsコードブロックを見つける。定義名を
@docsコードブロックに追加する。たとえば、関数barにdocstringを追加した場合、julia "..." function bar(args...) # ... end@docsブロック内のbarという名前を、doc/src/stdlib/に追加します。```@docs foo bar # <-- Added this one. baz ```ルートディレクトリで
make docsを実行する。doc/_build/htmlの出力を確認し、変更が正しいことを確かめる。変更をコミットし、プルリクエストを作成する。
Doctests
docstring内の例は、コードブロックにjldoctestを付けることで、「doctest」と呼ばれるテストケースとして実行できます。
```jldoctest
julia> uppercase("Docstring test")
"DOCSTRING TEST"
```doctestは、julia>プロンプトを含む対話型REPLと一致している必要があります。doctestの前に# Examplesヘッダーを追加することをおすすめします。
一般的なケースでのdoctestの書き方については、ベストプラクティスを説明したwriting jldoctestsのドキュメントを参照してください。また、doctestの実行方法についてはdoc/README.mdファイルを参照してください。