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/にあります。既存ファイルのテキストを更新または追加するには、次の手順に従います。

  1. 該当する.mdファイルのテキストを更新する。
  2. ルートディレクトリでmake docsを実行する。
  3. doc/_build/html/の出力を確認し、変更が正しいことを確かめる。
  4. 変更をコミットし、プルリクエストを作成する。

注

変更を加えた場合でも、doc/_build/の内容をコミットする必要はありません。

ファイルを更新するのではなく、doc/src/に新しいファイルを追加する場合は、上記の手順1を次の手順に置き換えます。

  1. 適切なdoc/src/サブディレクトリにファイルを追加し、doc/make.jl内のPAGESベクターにもファイルパスを追加する。

Modifying an existing docstring in base/

docstringは、対象となるメソッドや型の直前にインラインで記述されています。HTMLファイルで各docstringの下に表示されるsourceリンクをクリックすると、その場所を確認できます。既存のdocstringを変更する手順は次のとおりです。

  1. base/でdocstringを見つける。
  2. docstringのテキストを更新する。
  3. ルートディレクトリでmake docsを実行する。
  4. doc/_build/html/の出力を確認し、変更が正しいことを確かめる。
  5. 変更をコミットし、プルリクエストを作成する。

Adding a new docstring to base/

新しいdocstringを追加するには、次の手順に従います。

  1. docstringの対象として最も適切な定義をbase/で見つける。

  2. 定義の直前にdocstringを追加する。

  3. docstringを表示したいdoc/src/stdlib/ファイルのいずれかで、適切な@docsコードブロックを見つける。

  4. 定義名を@docsコードブロックに追加する。たとえば、関数barにdocstringを追加した場合、

    julia "..." function bar(args...) # ... end

    @docsブロック内のbarという名前を、doc/src/stdlib/に追加します。

     ```@docs
     foo
     bar # <-- Added this one.
     baz
     ```
  5. ルートディレクトリでmake docsを実行する。

  6. doc/_build/htmlの出力を確認し、変更が正しいことを確かめる。

  7. 変更をコミットし、プルリクエストを作成する。

Doctests

docstring内の例は、コードブロックにjldoctestを付けることで、「doctest」と呼ばれるテストケースとして実行できます。

```jldoctest
julia> uppercase("Docstring test")
"DOCSTRING TEST"
```

doctestは、julia>プロンプトを含む対話型REPLと一致している必要があります。doctestの前に# Examplesヘッダーを追加することをおすすめします。

一般的なケースでのdoctestの書き方については、ベストプラクティスを説明したwriting jldoctestsのドキュメントを参照してください。また、doctestの実行方法についてはdoc/README.mdファイルを参照してください。