Package Guide

Documenterは、1つのことを行うように設計されています - MarkdownファイルとJuliaのドキュメントシステムからのインラインドキュメント文字列を組み合わせて、相互にリンクされた単一のドキュメントを作成します。以下は、シンプルなドキュメントを作成するためのステップバイステップガイドです。

Installation

DocumenterはJuliaパッケージマネージャを使用してインストールできます。Julia REPLから、]を入力してPkg REPLモードに入り、次のコマンドを実行します。

pkg> add Documenter

パッケージのドキュメント作成のための標準的なアプローチは、パッケージの docs/ サブディレクトリに保存されたドキュメント専用のプロジェクトに Documenter をインストールすることです。これを行うには、パッケージのルートフォルダに移動し、次のコマンドを実行します。

pkg> activate docs/

(docs) pkg> add Documenter

これにより、docs/ サブディレクトリに Project.toml と Manifest.toml ファイルが作成されます。

パッケージの場合、ドキュメント化しているパッケージが "dev dependency" の docs/ 環境にある必要があることに注意してください。

See also the Pkg.jl documentation on working with project environments.

Setting up the Folder Structure

まず、ドキュメント化するためのJuliaモジュールが必要です。これは、PkgDev.generateを介して生成されたパッケージや、JuliaのLOAD_PATHを介してアクセス可能な単一の.jlスクリプトである可能性があります。このガイドでは、次のディレクトリレイアウトを持つExample.jlというパッケージを使用します。

Example/
├── src/
│   └── Example.jl
...

...は重要でないファイルやフォルダーを表しています。

このパッケージのドキュメントを保存する場所を決定する必要があります。パッケージのトップレベルに docs/ という名前のフォルダーを使用することをお勧めします。

Example/
├── docs/
│   └── ...
├── src/
│   └── Example.jl
...

docs/ フォルダー内に2つのものを追加する必要があります。完成したドキュメントを構築するために使用されるマークダウンファイルを含むソースフォルダーと、ビルドプロセスを制御するために使用されるJuliaスクリプトです。以下の名前が推奨されます。

docs/
├── src/
└── make.jl

Building an Empty Document

docs/ ディレクトリが設定されたので、最初のドキュメントを作成します。現時点では単なる空のファイルになりますが、後で追加していく予定です。

make.jlファイルに以下を追加してください。

using Documenter, Example

makedocs(sitename="My Documentation")

これは、Installationで説明したようにDocumenterをインストールし、あなたのExample.jlパッケージがJuliaによって見つけられることを前提としています。もしあなたのパッケージがリモートのgitリポジトリではなく、ローカルパスを使用して開発依存関係として追加されている場合、関数makedocsにキーワード引数remotes = nothingを追加する必要があります。

push!(LOAD_PATH,"../src/")

src/ディレクトリにindex.mdファイルを追加してください。

新しく追加したファイルは空のままにしておき、次のコマンドを docs/ ディレクトリから実行してください。

$ julia --project make.jl

Note that $ just represents the prompt character. You don't need to type that.

このコマンドの出力をカラーで表示したい場合は、使用してください。

$ julia --color=yes --project make.jl

それを実行すると、次の出力が表示されるはずです。

[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.

docs/ フォルダーには新しいディレクトリ – build/ と呼ばれるもの – が含まれている必要があります。その構造は以下のようになります。

build/
├── assets
│   ├── documenter.js
│   ├── themes
│   │   ├── documenter-dark.css
│   │   └── documenter-light.css
│   ├── themeswap.js
│   └── warner.js
├── index.html
├── search
│   └── index.html
└── search_index.js

makedocs(...,
    format = Documenter.HTML(
        prettyurls = get(ENV, "CI", nothing) == "true"
    )
)

この時点で build/index.html は空のページであるべきです。なぜなら src/index.md が空だからです。src/index.md にいくつかのテキストを追加し、変更を確認するために make.jl ファイルを再実行してみてください。

Adding Some Docstrings

次に、Exampleモジュールで定義されたドキュメント文字列をindex.mdファイルに挿入します。これを行うために、まずそのモジュール内の関数を文書化します：

module Example

export func

"""
    func(x)

Return double the number `x` plus `1`.
"""
func(x) = 2x + 1

end

次に、src/index.mdファイルに以下を追加します。

# Example.jl Documentation

```@docs
func(x)
```

次に make.jl を実行すると、Example.func(x) のドキュメント文字列が build/index.md の @docs ブロックの代わりに表示されるはずです。@docs ブロック内には 複数の オブジェクトを参照することができることに注意してください – 各オブジェクトを別々の行に置くだけです。

@docs ブロックは Main モジュールで評価されることに注意してください。これは、ブロック内にリストされた各オブジェクトがそこに見える必要があることを意味します。モジュールは、以下のように @meta ブロックを使用してページごとに別のものに変更できます。

# Example.jl Documentation

```@meta
CurrentModule = Example
```

```@docs
func(x)
```

Filtering included docstrings

場合によっては、異なるモジュール（例えば Base）からの Function を拡張する Method のためにドキュメント文字列を含めたいことがあります。以下の例では、構造体 T のための新しい定義で Base.length を拡張し、ドキュメント文字列も追加しています：

struct T
    # ...
end

"""
Custom `length` docs for `T`.
"""
Base.length(::T) = 1

このドキュメント文字列を含めようとするときに

```@docs
length
```

lengthに関するすべてのドキュメントが含まれます - 他のモジュールからのものも含めて。この問題を解決する方法は2つあります。型をシグネチャに含めるか、

```@docs
length(::T)
```

または、makedocs が含むべき特定のモジュールを宣言します。

makedocs(
    # options
    modules = [MyModule]
)

Cross Referencing

特定のドキュメントのドキュメント文字列やセクションを、ドキュメント内の他の場所から参照する必要があるかもしれません。これを行うために、Documenterのクロスリファレンス構文を利用することができます。この構文は通常のマークダウンリンク構文に非常に似ています。src/index.mdの内容を以下のように置き換えてください。

# Example.jl Documentation

```@docs
func(x)
```

- link to [Example.jl Documentation](@ref)
- link to [`func(x)`](@ref)

各リンクのURLを@refに置き換え、参照先の名前を記述するだけです。ドキュメントのヘッダーの場合は、ヘッダーの名前と一致するプレーンテキストで、ドキュメント文字列の場合はオブジェクトをバッククォートで囲みます。

これも同様に異なるページ間で機能します。これらのセクションとドキュメント文字列は、ドキュメント内で一意である必要があることに注意してください。

External Cross-References

任意のプロジェクトが最新のDocumenterリリースを使用してドキュメントを構築すると、objects.inv inventoryが生成され、deployed documentationのルートに見つけることができます。DocumenterInterLinks pluginは、外部プロジェクト名とそのインベントリファイルとの間のマッピングをmake.jlファイルで定義することを可能にします。例えば、

using DocumenterInterLinks

links = InterLinks(
    "Documenter" => "https://documenter.juliadocs.org/stable/objects.inv"
)

その InterLinks オブジェクトは、makedocs の plugins の要素として渡されるべきです。これにより、Documenter パッケージの外部ドキュメントにクロスリファレンスする機能が有効になります。例えば、上記の @extref link と似た構文を持つ @ref を使用して、例えば、

See the [`Documenter.makedocs`](@extref) function.

See the documentation of the DocumenterInterLinks package for more details.

Navigation

Documenterは、次の構文を使用してドキュメントの目次とドキュメント文字列インデックスを自動生成できます。これらの機能を、前のセクションのindex.mdファイルを使用して説明します。そのファイルに以下を追加してください。

# Example.jl Documentation

```@contents
```

## Functions

```@docs
func(x)
```

## Index

```@index
```

@contents ブロックは、ドキュメント内のすべてのセクションヘッダーへのリンクのネストされたリストを生成します。デフォルトでは、ドキュメント内のすべてのページからレベル 1 および 2 のヘッダーを収集しますが、これは以下のように Pages および Depth 設定を使用して調整できます。

```@contents
Pages = ["foo.md", "bar.md"]
Depth = 3
```

@index ブロックは、@docs ブロックを使用して文書にスプライスされたすべてのドキュメントへのリンクのフラットリストを生成します。@contents ブロックと同様に、含めるページは Pages = [...] 行で設定できます。リストがネストされていないため、@index では Depth はサポートされていません。

Pages in the Sidebar

デフォルトでは、ソースディレクトリ内のすべてのページ（.mdファイル）がサイドバーに追加され、ファイル名でソートされます。しかし、ほとんどの場合、サイドバーの見た目を制御するためにpages引数をmakedocsを使用したいと思うでしょう。基本的な使用法は以下の通りです：

makedocs(
    ...,
    pages = [
        "page.md",
        "Page title" => "page2.md",
        "Subsection" => [
            ...
        ]
    ]
)

pages 引数を使用すると、ページをサブセクションに整理し、hide 関数の助けを借りてサイドバーからいくつかのページを隠すことができます。

Adding a logo or icon

ドキュメントにロゴやアイコンを簡単に追加でき、ナビゲーションサイドバーに自動的に表示されます。

ビルドプロセス中、Documenterはsrc/assets/ディレクトリ内の適切なグラフィック画像を探し、自動的に/build/assets/にコピーします。

SVG、PNG、WEBP、GIF、またはJPEG画像を使用できます。

Documenterは、logo.svg、logo.png、logo.webp、logo.gif、logo.jpg、またはlogo.jpegのファイルを、その順序で探します。最初に見つかった適切な画像が使用されます。

この画像は、ライトテーマとダークテーマの両方で使用されます。ダークテーマ用に別のデザインを作成したい場合は、logo-dark.svg（またはPNG/WEBP/GIF/JPEG）というファイルを追加してください。

ファイルは正方形である必要はありません。透明な背景を持つ画像は、特にダークテーマではより良く見えることがあります。

Documenter.HTML の sidebar_sitename キーワードオプションを使用すると、通常ロゴの下に表示されるサイト名を非表示にすることができます。これは、ロゴにすでに名前が含まれている場合に便利です。