fortran-lang.org のミニブックチュートリアル#

このガイドでは、Learn セクションの https://fortran.dokyumento.jp 用のミニブックチュートリアルを作成する方法について説明します。

貢献ガイドラインを参照して、https://fortran.dokyumento.jp への貢献に関する一般的なガイダンスを確認してください。

0. ミニブックの形式#

ミニブックは、Fortran 言語の特定の機能に関するほとんど自己完結型のチュートリアルとして設計されています。

ミニブックには 2 つの形式があります。

単一ページ: すべてのコンテンツが単一のマークダウンファイル内に記述され、単一の Web ページに表示されます。
複数ページ: チュートリアルコンテンツが複数のマークダウンファイルに記述され、Web ページのコレクションとして表示されます。

ブックタイプの選択は、コンテンツの長さと、コンテンツをどのように構成するかによって異なります。

生成される目次を考慮してください。

単一ページブックには、1 つのレベルのナビゲーションがあります。ページ内 toc (ページの右側にある toc) にチュートリアルの各見出しへのリンクがあります。
複数ページブックには、2 つのレベルのナビゲーションがあります。ページ内 toc (ページの右側にある toc) にチュートリアルの各見出しへのリンクと、サイドバー toc (ディレクトリ内の異なるページを表示するページの左側にある toc) があります。

単一ページのミニブックは作成が簡単で、短いトピックや、最終的にはより包括的な複数ページのブックに組み込まれる短いチュートリアルに使用する必要があります。

複数ページのブックは、1 ページあたり 1 つのサブトピックで構成できる、より包括的なチュートリアルに推奨されます。

このガイドの残りの部分は、単一ページと複数ページのブックタイプごとに 2 つのセクションに分かれています。

1. 単一ページのミニブック#

単一ページのミニブックを公開するために必要な手順は次のとおりです。

./learn ディレクトリに新しいマークダウンドキュメントを作成します
チュートリアルコンテンツを作成します
新しいミニブックのdata/learning.yml にエントリを追加します
プルリクエストを開きます

1.1 マークダウンでのミニブックの作成#

単一ページのミニブックの場合、チュートリアルはすべて単一のマークダウンドキュメントに含まれます。

まず、./learn/{{name_of_minibook}}/ ディレクトリに、.md ファイル拡張子とチュートリアルのトピックを簡潔に説明する短い名前 (例: ./learn/{{name_of_minibook}}/file_io.md) を持つ新しいマークダウンドキュメントを作成します。

新しいマークダウンファイルを開き、次の形式で learn.md の toc にエントリを追加します

:::{toctree}
:hidden:

learn/quickstart/index
learn/best_practices/index
learn/os_setup/index
learn/building_programs/index
learn/intrinsics/index
learn/{{book-filename}}
:::

{{book-filename}} をマークダウンファイルのファイル名に置き換えますが、.md 拡張子を除きます。末尾にスラッシュを付けることもできません。

例: ヘッダー

:::{toctree}
:hidden:

learn/quickstart/index
learn/best_practices/index
learn/os_setup/index
learn/building_programs/index
learn/intrinsics/index
learn/file_io
:::

非推奨: permalink: /learn/file_io.md

非推奨: permalink: /learn/file_io/

これで、残りのファイルに、マークダウンで記述されたチュートリアルコンテンツを入力できます。マークダウンの実装については、Kramdown 構文を参照してください。

1.2 見出しを使用したミニブックの構成#

見出しを使用して、単一ページのミニブックを論理的な構造に分割する必要があります。各見出しは、ハイパーリンクされた目次に表示されます。

マークダウンでは、見出しは次のように記述できます。

# Heading level 1

## Heading level 2

### Heading level 3

#### Heading level 4

##### Heading level 5

###### Heading level 6

注: 見出しの前に空白行を含めるようにしてください。

1.3 ミニブックを [学ぶ] ページに追加する#

新しいミニブックを学ぶページに追加するには、data/learning.yml データファイルに新しいエントリを追加する必要があります。

このファイルを開き、books: フィールドの下に次の形式で新しいエントリを作成します。

- title: {{book-title}}
  description: {{book-description}}
  category: {{book-category}}
  link: /learn/{{book-filename}}

title フィールドは、ミニブックの学ぶページに表示される内容であり、通常はマークダウンファイルの title フィールドと同じにする必要がありますが、必須ではありません。

description フィールドの内容も学ぶページに表示され、ミニブックチュートリアルの内容を簡単に要約する必要があります。

category フィールドは、データファイルの先頭 ( categories: フィールドの下) にリストされているカテゴリのいずれかと一致する必要があり、[学ぶ] ページのチュートリアルをグループ化するために使用されます。

link フィールドは、マークダウンドキュメントの permalink フィールドと完全に一致する必要があります。

例: learning.yml ブックエントリ

- title: File input and output
  description: A tutorial on reading and writing files in Fortran
  category: Getting started
  link: /learn/file/file_io

変更した learning.yml データファイルを保存し、fortran_package.py を実行して、ローカルマシンでウェブサイトを再構築し、結果を確認します。成功すると、新しいミニブックのタイトルが _学ぶ* ページに新しいリンクとして表示されます。

ミニブックを完了し、learning.yml データファイルにエントリを追加したら、https://github.com/fortran-lang/webpage でプルリクエストを開きます ( CONTRIBUTING を参照)。

2. 複数ページのミニブック#

複数ページのミニブックを公開するために必要な手順は次のとおりです。

./learn/ ディレクトリに新しいフォルダーを作成します
新しいフォルダーに index.md ファイルを作成します
新しいフォルダーのマークダウンファイルにチュートリアルコンテンツを記述します
新しいミニブックのdata/learning.yml にエントリを追加します
プルリクエストを開きます

2.1 ミニブックの新しいフォルダーを作成する#

チュートリアルのトピックを簡潔に説明する短い名前 (例: ./learn/coarrays/) を持つ新しいフォルダーを ./learn/ ディレクトリに作成します。ミニブックのすべてのページはこのフォルダーに格納されます。

ミニブックの最初のページは index.md という名前である必要があります。そのため、ミニブックフォルダーに index.md という名前の新しいマークダウンファイルを作成し、すべてのマークダウンファイルに次の形式で toc を追加します

:::{toctree}
:hidden:

file1
file2
:::

末尾にスラッシュを付けることはできません。

例: index.md の toc

:::{toctree}
:hidden:

learn/quickstart/index
learn/best_practices/index
learn/os_setup/index
learn/building_programs/index
learn/intrinsics/index
:::

非推奨: permalink: /learn/coarrays/

index.md の残りの部分に、ミニブックチュートリアルの概要を入力する必要があります。これには、カバーする概念の要約、前提条件、およびその他の関連ミニブックまたは役立つサードパーティリソースへの参照を含めることができます。

2.2 ミニブックにページを追加する#

ミニブックの新しいページごとに、ミニブックフォルダーに新しいマークダウンファイルを作成します。

単一ページのミニブックと同様に、見出しを使用して各ページを論理的な構造に分割する必要があります。現在のページの各見出しは、ページ内目次に表示されます。

2.3 ミニブックを [学ぶ] ページに追加する#