Showcase

このページでは、Documenterによってサポートされているさまざまなページ要素を紹介しています。さまざまな要素を作成するために正確に使用されている構文を見るために、そのソース（docs/src/showcase.md）と並行して読むべきです。

Table of contents

目次は @contents block を使用して生成できます。このページの目次は次のように表示されます。

• Showcase
• • Table of contents
  • Basic Markdown
  • Code blocks
  • Mathematics
  • Images
  • Admonitions
  • Lists
  • Tables
  • Footnotes
  • Headings
  • Docstrings
  • Doctesting example
  • Running interactive code

Basic Markdown

DocumenterはすべてのMarkdown syntax supported by the Julia Markdown parserをレンダリングできます。太字テキストや斜体テキスト、print("インラインコード")など、すべての通常のマークダウン構文を使用できます。

Code blocks

コードブロックは次のようにレンダリングされます：

This is an non-highlighted code block.
... Rendered in monospace.

ブロックの言語が指定されている場合、例えばブロックを ```julia で始めることで、内容が適切にハイライトされます（ハイライターによってサポートされている言語の場合）。

function foo(x::Integer)
    @show x + 1
end

Mathematics

数学において、インラインおよび表示形式の方程式がサポートされています。インライン方程式は、2つのバックティックの間にLaTeXとして記述する必要があります。例えば、``A x^2 + B x + C = 0``のように記述します。これは$A x^2 + B x + C = 0$としてレンダリングされます。

表示方程式のためのLaTeXは、```math コードブロックで囲む必要があり、次のようにレンダリングされます。

\[x_{1,2} = \frac{-B \pm \sqrt{B^2 - 4 A C}}{2A}\]

デフォルトでは、HTML出力はKaTeXで数式をレンダリングしますが、MathJaxもオプションとして使用できます。

Images

基本的なMarkdown構文を使用して画像を含める:

パスは現在のファイルのディレクトリに対して相対的であるべきです。あるいは、./を使用してドキュメントのsrcに対して相対的なパスを始めることができます。例えば、./assets/logo.pngのように。

Admonitions

注意書きは、ドキュメントの一部を強調するために使用されるカラフルなボックスです。

各注意喚起は三つの!!!で始まり、その後に内容が四つのスペースでインデントされています：

!!! note "An optional title"
    Here is something you should pay attention to.

Documenterは、さまざまな状況に応じたアドモニションタイプをサポートしています。

Note admonition

f(x) = x^2

Info admonition

Tip admonition

Warning admonition

Danger admonition

Compat admonition

TODO admonition

Details admonition

タイプ details の注意書きは、HTML出力で折りたたまれた <details> ブロックとしてレンダリングされ、注意書きのタイトルが <summary> として表示されます。

Unknown admonition class

Lists

タイトリストは次のようになります。

• ロレム・イプサム・ドル・シット・アメット、コンセクテトゥール・アディピスシング・エリート。
• Nulla quis venenatis justo.
• In non sodales eros.

リストに段落やその他のブロックレベル要素が含まれている場合、次のようになります：

• Morbi et varius nisl, eu semper orci.

  Donec vel nibh sapien. Maecenas ultricies mauris sapien. Nunc et sem ac justo ultricies dignissim ac vitae sem.

• Nulla molestie aliquet metus, a dapibus ligula.

  モルビ ペレンテスケンテ ソダレス ソリシチュディン。フスケ センペル プラケラット スシピット。アリカム センペル テンプス エクス、ノン エフィキトゥール エラット ポスイレ イン。フスケ アット オルキ エウ エクス サギッティス コモド。

  Fusce tempus scelerisque egestas. Pellentesque varius nulla a varius fringilla.

  Fusce nec urna eu orci porta blandit.

番号付きリストもサポートされています

1. ロレム・イプサム・ドル・シット・アメット、コンセクテトゥール・アディピスシング・エリート。
2. Nulla quis venenatis justo.
3. In non sodales eros.

ネストされたリストとして

• Morbi et varius nisl, eu semper orci.

  Donec vel nibh sapien. Maecenas ultricies mauris sapien. Nunc et sem ac justo ultricies dignissim ac vitae sem.

  • Lorem ipsum dolor sit amet, consectetur adipiscing elit.
  • Nulla quis venenatis justo.
  • In non sodales eros.

• Nulla molestie aliquet metus, a dapibus ligula.

  1. ロレム・イプサム・ドル・シット・アメット、コンセクテトゥール・アディピスシング・エリート。
  2. Nulla quis venenatis justo.
  3. In non sodales eros.

  Fusce nec urna eu orci porta blandit.

リストは、ブロックレベルのアイテムを含む他のブロックにも含めることができます。

• Morbi et varius nisl, eu semper orci.

  Donec vel nibh sapien. Maecenas ultricies mauris sapien. Nunc et sem ac justo ultricies dignissim ac vitae sem.

  • ロレム・イプサム・ドル・シット・アメット、コンセクテトゥール・アディピスシング・エリート。
  • Nulla quis venenatis justo.
  • In non sodales eros.

Tables

明示的な整列。

幅が広すぎるテーブルはスクロール可能にする必要があります。

Footnotes

脚注の参照は [^label] 構文を使って追加できます。^[1] 脚注の定義はページの下部に集められます。

脚注ラベルは任意の文字列であり、ブロックレベルの要素で構成されることもあります。^[Clarke61]

Headings

最終的に、見出しは次のようにレンダリングされます

Heading level 3

Heading level 4

Heading level 5

Heading level 6

レベル1見出しの例を見るにはページタイトルを参照し、レベル2見出しについてはこの段落のすぐ下にあるものを参照してください。

ドキュメント文字列では、見出しが現在は単に太字のテキストとして書き換えられることに注意してください：

baz(x, f, k)

Docstrings

Documenterの主な機能は、もちろん、パッケージからのドキュメント文字列をマニュアルに自動的に含める能力です。以下の例のドキュメント文字列は、デモの DocumenterShowcase モジュールからのもので、そのソースは docs/DocumenterShowcase.jl にあります。

マニュアルページにドキュメント文字列を含めるには、@docs blockを使用する必要があります。

```@docs
DocumenterShowcase
```

これは単一のドックストリングを含み、次のようになります：

println("Hello World")

異なる関数シグネチャに対応するドキュメント文字列を1つずつ含めることができます。例えば、DocumenterShowcase.foo 関数には2つのシグネチャがあります - (::Integer) と (::AbstractString)。

```@docs
DocumenterShowcase.foo(::Integer)
```

次のドキュメント文字列を生成します。

foo(::Integer)

そして、@docsブロックにDocumenterShowcase.foo(::AbstractString)を持つことで、別のドキュメント文字列が得られます。

foo(::AbstractString)

しかし、希望があれば、複数のドキュメント文字列を1つのドキュメント文字列ブロックにまとめることもできます。これを示すために、DocumenterShowcase.bar 関数は DocumenterShowcase.foo と同じシグネチャを持っています。もし DocumenterShowcase.bar を @docs ブロックに入れるだけであれば、ドキュメント文字列は次のように結合されます：

bar(::Integer)

bar(::AbstractString)

もし非常に多くのドキュメント文字列がある場合、特定のフィルタリングオプションに基づいてドキュメント文字列の全セットを自動的に含めることができる @autodocs block の使用を検討することもできます。

両方の @docs と @autodocs は 4d61726b646f776e2e436f64652822222c202263616e6f6e6963616c3d66616c73652229206b6577776f726420617267756d656e74_40726566206e6f6e63616e6f6e6963616c2d626c6f636b をサポートしています。これを使用すると、ドキュメント文字列を複数回含めることができます。例えば、これを行うと...

```@docs; canonical=false
DocumenterShowcase.bar
```

... その後、上記と同じドックストリングが表示されます：

bar(::Integer)

bar(::AbstractString)

An index of docstrings

@index block を使用して、ページ上のすべてのドキュメント文字列のリストを生成することができ（ページをまたいででも）、次のようになります：

• DocumenterShowcase
• Main.DocumenterShowcase.Foo
• Main.DocumenterShowcase.Foo
• Main.DocumenterShowcase.Foo
• Main.DocumenterShowcase.bar
• Main.DocumenterShowcase.baz
• Main.DocumenterShowcase.foo
• Main.DocumenterShowcase.foo

Multiple uses of the same symbol

時には、シンボルに複数のドキュメント文字列があることがあります。たとえば、型定義、内部および外部コンストラクタです。以下の例は、ドキュメント内で特定のものを使用する方法を示しています。

```@docs
DocumenterShowcase.Foo
DocumenterShowcase.Foo()
DocumenterShowcase.Foo{T}()
```

これは次のようにレンダリングされます：

Doctesting example

しばしば、このようなコード例を書きたいと思います:

julia> f(x) = x^2
f (generic function with 1 method)

julia> f(3)
9

もしそれらを ```jldoctest コードブロックとして書くと、Documenter はドクトテストが古くなっていないことを確認できます。詳細については Doctests を参照してください。

スクリプトスタイルのドクトテストもサポートされています:

2 + 2
# output
4

Setup code

ドクトテストの前に実行されるセットアップコードを持つことができます。たとえば、次のドクトテストでは、Documenterモジュールが存在する必要があります。

julia> Documenter.splitexpr(:(Foo.Bar.baz))
(:(Foo.Bar), :(:baz))

これは jldoctest の setup キーワードによって実現されます。

```jldoctest; setup=:(using Documenter)

代替アプローチは、@metaブロック内のDocTestSetupキーを使用することであり、これにより複数のドクトテストに適用されます。

```@meta
DocTestSetup = quote
  f(x) = x^2
end
```

julia> f(2)
4

ドクトテストと @meta ブロックは各ページで順次評価されるため、テストコードを nothing に戻すことで常に解除できます。

```@meta
DocTestSetup = nothing
```

Teardown code

前のセクションで説明したセットアップコードに加えて、実際のドクトテストの後に実行されるコードがあると便利です。これは、設定を復元したり、セットアップ中に取得したリソースを解放したりするためです。たとえば、次のドクトテストは、setprecisionがBigFloatのデフォルト精度を変更するために使用されたことを期待しています。テストが完了した後、これを以前の設定に戻す必要があります。

julia> sqrt(big(2.0))
1.4142132

これは、setupに加えてjldoctestのteardownキーワードによって実現されます。

```jldoctest; setup=:(oldprec=precision(BigFloat);setprecision(BigFloat,20)), teardown=:(setprecision(BigFloat,oldprec))

注意してください。もし今、同じdoctestの内容をsetupとteardownなしで再実行すると、異なる（より高い）精度の出力が得られます。もしteardownなしでsetupを使用していた場合、このdoctestは依然として小さい精度を使用し、つまり前のdoctestの影響を受けることになりますが、これは私たちが望んでいることではありません。

julia> sqrt(big(2.0))
1.414213562373095048801688724209698078569671875376948073176679737990732478462102

代替アプローチは、@metaブロック内のDocTestSetupおよびDocTestTeardownキーを使用することであり、これにより複数のドクトテストに適用されます。

```@meta
DocTestSetup = quote
  oldprec = precision(BigFloat)
  setprecision(BigFloat, 20)
end
DocTestTeardown = quote
  setprecision(BigFloat, oldprec)
end
```

julia> sqrt(big(2.0))
1.4142132

ドクトテストと @meta ブロックは各ページで順次評価されるため、テストコードを nothing に戻すことで常に解除できます。

```@meta
DocTestSetup = nothing
DocTestTeardown = nothing
```

Running interactive code

@example block コードスニペットを実行し、その出力をドキュメントに挿入します。例えば、以下のMarkdown

```@example
2 + 3
```

次のコード-出力ブロックペアになります。

2 + 3

5

最後の要素が画像や text/html などとしてレンダリングできる場合（特定のMIMEタイプに対する対応する Base.show メソッドが定義されている必要があります）、適切にレンダリングされます。例えば：

using Main: DocumenterShowcase
DocumenterShowcase.SVGCircle("000", "aaa")

これは Markdown 標準ライブラリと組み合わせると便利です。

using Markdown
Markdown.parse("""
`Markdown.MD` objects can be constructed dynamically on the fly and still get rendered "natively".
""")

@exampleブロックの最後の値がnothingの場合、ブロックの評価からの標準出力が代わりに表示されます。

println("Hello World")

Hello World

ただし、ブロックが標準出力に出力を行い、かつ最終的にnothing以外の値を持つ場合、標準出力は単に破棄されることに注意してください。

println("Hello World")
42

42

Color output

@repl block と @example block の出力は、ANSI カラーコードを HTML に変換してカラフルな出力をサポートしています。

Colored @example block output

Please provide the Markdown content you would like to have translated into Japanese.

```@example
code_typed(sqrt, (Float64,))
```

出力:

code_typed(sqrt, (Float64,))

1-element Vector{Any}:
 CodeInfo(
1 ─ %1 = Base.lt_float(x, 0.0)::Bool
└──      goto #3 if not %1
2 ─      invoke Base.Math.throw_complex_domainerror(:sqrt::Symbol, x::Float64)::Union{}
└──      unreachable
3 ─ %5 = Base.Math.sqrt_llvm(x)::Float64
└──      return %5
) => Float64

Colored @repl block output

Please provide the Markdown content you would like me to translate into Japanese.

```@repl
printstyled("This should be in bold light cyan.", color=:light_cyan, bold=true)
```

出力:

julia> printstyled("This should be in bold cyan.", color=:cyan, bold=true)This should be in bold cyan.

ローカルで無効化された色:

```@repl; ansicolor=false
printstyled("This should be in bold light cyan.", color=:light_cyan, bold=true)
```

julia> printstyled("This should be in bold light cyan.", color=:light_cyan, bold=true)This should be in bold light cyan.

Raw ANSI code output

色設定に関係なく、ANSIエスケープコードを直接印刷すると、色付けが有効になります。

for color in 0:15
    print("\e[38;5;$color;48;5;$(color)m  ")
    print("\e[49m", lpad(color, 3), " ")
    color % 8 == 7 && println()
end
print("\e[m")

    0     1     2     3     4     5     6     7
    8     9    10    11    12    13    14    15

REPL-type

@repl block は、コードブロックのREPL評価をシミュレートするために使用できます。たとえば、次のブロック

```@repl
using Statistics
xs = collect(1:10)
median(xs)
sum(xs)
```

それは、julia> プロンプトが前に付け加えられた状態で、REPLで評価されたかのように見えるものに展開されます。

julia> using Statistics
julia> xs = collect(1:10)10-element Vector{Int64}:
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
julia> median(xs)5.5
julia> sum(xs)55

Named blocks

一般に、各ブロックは別のクリーンなコンテキストで評価されます（つまり、前のブロックからの変数が名前空間を汚染することはありません）。ただし、ブロックに名前を付けることで名前空間を再利用することもできます。

```@example block-name
x = 40
```
will show up like this:

x = 40

40

```@example block-name
x + 1
```
will show up like this:

x + 1

41

ドキュメントに表示したくないセットアップコードが必要な場合は、次のように使用できます an @setup block:

```@setup block-name
x = 42
```

@setup blockは、実質的に隠れた@example blockとして機能します。設定した状態は、同じ名前で後続のブロックでアクセスできます。たとえば、次の@exampleブロック

```@example block-name
x
```

このように表示されます：

x

42

あなたは即座に評価されない継続ブロックも持っています。

```@example block-name; continued = true
y = 99
```

y = 99

継続的な評価は、@example blocks にのみ適用されるため、例えばその間に @repl ブロックを入れると、y = 99 のコード行がまだ実行されていないため、エラーが発生します。

```@repl block-name
x
y
```

julia> x42
julia> yERROR: UndefVarError: `y` not defined in `Main.var"Main"`
Suggestion: check for spelling errors or missing imports.

別の @example block 同じ名前のものは、評価を完了します。したがって、次のようなブロックが必要です。

```@example block-name
(x, y)
```

will lead to

(x, y)

(42, 99)