重要

翻訳は あなたが参加できる コミュニティの取り組みです。このページは現在 100.00% 翻訳されています。

19. 付録：このマニュアルに貢献する

このコースに教材を追加するには、この付録のガイドラインに従わなければなりません。明確にする場合を除き、この付録の条件を変更してはいけません。これは、このマニュアルの品質と一貫性を維持するためです。

19.1. リソースのダウンロード

この文書のソースは GitHub で提供されています。Gitのバージョン管理システムを使用する方法については、 GitHub.com を参照してください。

19.2. マニュアルの形式

このマニュアルは、reStructuredText マーク付け言語を使ったPythonドキュメントジェネレータ、Sphinx を使って書かれました。これらのツールの使い方はそれぞれのサイトで入手できます。

19.3. モジュールを追加する

新しいモジュールを追加するには:

  1. 最初に新しいモジュールの名前を持った新しいディレクトリを（ qgis-training-manual ディレクトリのトップレベルのすぐ下に）作成します。

  2. この新しいディレクトリの下に、 index.rst というファイルを作成します。今のところ、このファイルは空のままにします。

  3. 最上位ディレクトリの下の index.rst ファイル開きます。その最初の数行は:

    .. toctree::
   :maxdepth: 2

   foreword/index
   introduction/index

これは、名前 index が続く、ディレクトリ名のリストであることに注意します。これは、トップレベルのインデックスファイルに各ディレクトリ内のインデックスファイルを指示します。リストされている順序で文書中の順序が決定されます。

  1. このリストのモジュールを表示したい場所に、新しいモジュールの名前（すなわち、新しいディレクトリに付けた名前）に /index を続けたものを追加します。

  2. 後のモジュールは前のモジュールで提示される知識の上に構築するように、モジュールの順序を論理的に維持することを忘れないでください。

  3. 新しいモジュールの独自のインデックスファイル（ module_name/index.rst ）を開きます。

  4. ページの先頭に沿ってモジュールの見出しを作ります:

    1. アスタリスク(*)の最初の行を書きます。

    2. Module: というマークアップ語句の後に、モジュールの名前を付けた１行を続けます。

    3. 同じ数のアスタリスクをもう1行書いて終えます。

    注釈

    アンダーラインとオーバーラインは、モジュールの表題を含む行よりも短くすべきではありません。

  5. この下に空白行を置きます。

  6. モジュールの目的と内容を説明する短い段落を書きます。

  7. 1行を空白のままに残し、次のテキストを追加します:

    .. toctree::
   :maxdepth: 2

   lesson1
   lesson2

    ...ここで、lesson1 、 lesson2 などは、計画したレッスンの名前です。

モジュールレベルのインデックスファイルは次のようになります。

*******************************************************************************
Module: Module Name
*******************************************************************************

Short paragraph describing the module.

.. toctree::
   :maxdepth: 2

   lesson1
   lesson2

19.4. レッスンを追加する

新規または既存のモジュールにレッスンを追加するには:

  1. モジュールディレクトリを開きます。

  2. index.rst ファイル（新しいモジュールの場合に上で作成）を開きます。

  3. 計画したレッスンの名前が、上で示されるように、 toctree ディレクティブ下に表示されていることを確認します。

  4. モジュールディレクトリの下に新しいファイルを作成します。

  5. このファイルにモジュールの index.rst ファイルの中に与えた名前とまったく同じ名前を付け、拡張子 .rst を追加します。

注釈

編集する目的では、 .rst ファイルは通常のテキストファイル（ .txt ）とまったく同じように動作します。

  1. レッスンを書き始めは、マークアップ語句 Lesson にレッスン名を続けて書きます。

  2. 次の行には、等号(=')の行をレッスンの表題より短くならないように書きます。

  3. この後に空行を置きます。

  4. レッスンの意図された目的について短い説明を書きます。

  5. 主題への一般的な紹介を含めます。例として、このマニュアル中の既存のレッスンを参照してください。

  6. この下には、この語句から始まる、新しい段落を開始します:

    **The goal for this lesson:**

  7. このレッスンを完了することによる意図した成果を簡単に説明します。

  8. 1つのまたは2つの文にレッスンの目標を記述できない場合は、主題を複数のレッスンに分けることを検討してください。

次に説明するように、各レッスンは複数のセクションに細分化されます。

19.5. セクションを追加する

セクションには、「理解しよう」と「自分でやってみよう」の2種類があります。

  • 「理解しよう」セクションは指示の詳細なセットで、QGISの所定の態様を使用する方法を読者に教示することを意図しています。これは通常、スクリーンショットを散りばめた状態で、クリックごとの指示をできる限り明確に示すことで行われます。

  • 「やってみよう」セクションは、読者に自分でやらせる短い課題を与えます。通常、その下には結び付いた解答欄があり、その課題を完了する方法を示したり、説明したり、可能であれば期待される結果を示したりします。

すべてのセクションには難易度が付けられています。簡単なセクションは ★☆☆ 、中級は ★★☆ 、そして上級は ★★★ で表されます。

19.5.1. 「理解しよう」セクションを追加する

  1. （上記のように）このセクションを開始するには、意図した難易度のマークアップ語句を書き込みます。

  2. スペースを置き、次に「理解しよう:」を書きます。

  3. もうひとつスペースを置いて、セクションの名前を書きます（初回のみ大文字だけでなく、固有名詞のための大文字を使用）。

  4. 次の行には、負号／ダッシュ(-')の行をセクションの表題より短くならないように書きます。

  5. その目的を説明し、セクションへの簡単な紹介を書きます。そして、例証される手続きについての詳細な（クリック毎の）指示を与えます。

  6. 必要に応じて各セクションには、内部リンク、外部リンク、およびスクリーンショットが含まれます。

  7. 可能ならば、それを終了し、次のセクションに自然につながる短い段落で、各セクションを終了してみてください。

19.5.2. 「自分でやってみよう」セクションを追加する

  1. （上記のように）このセクションを開始するには、意図した難易度のマークアップ語句を書き込みます。

  2. スペースを置き、次に「自分でやってみよう:」を書きます。

  3. 次の行には、負号／ダッシュ(-')の行をセクションの表題より短くならないように書きます。

  4. 読者に完成させたい練習を説明します。必要に応じて、前のセクション、レッスンやモジュールを参照します。

  5. 単なる文章での説明でははっきりしない場合、要件を明確にするためにスクリーンショットを含めます。

ほとんどの場合、このセクションで与えられた課題を完成する方法についての解答を提供したいと思うでしょう。そのためには、指示の下に解答ブロックを作って与える必要があります。

  1. まず、解答を格納するカスタム折りたたみウィジェットを作ります:

    .. admonition:: Answer
   :class: dropdown

  2. 上のブロックに対してインデントを保ちながら、必要に応じてリンクや画像を使い、課題を完了するための指示を書きます。

19.6. 結論を追加

レッスンを終えるには:

  1. 語句「結論」を書き、マイナス/ハイフン(-)の新しい行を続けます。

  2. どの概念がレッスンで取り扱われたかを説明しながら、レッスンの結論を書きます。

19.7. 参考文献セクションを追加

このセクションは任意です。

  • 語句「参考文献」を書き、マイナス/ハイフン（ - ）の新しい行を続けます。

  • 適切な外部のウェブサイトへのリンクを含めます。

19.8. [次は]セクションを追加

  1. 語句「次は?」を書き、マイナス/ハイフン (-)の新しい行を続けます。

  2. このレッスンがどのように学生にとって次のレッスンまたはモジュールの準備になったかを説明します。

  3. 必要であれば前のレッスンの「次は」のセクションを、新しいレッスンを参照するように変更することを忘れないでください。これは既存のレッスンの間に、または既存のレッスンの後に新しいレッスンを挿入した場合に必要となります。

19.9. マークアップを使用する

このドキュメントの基準を遵守するため、テキストに標準的なマークアップを追加する必要があります。

19.9.1. 新しい概念

新しい概念を説明している場合は、その新しい概念の名前をアスタリスク (*)で囲んで斜体で記述する必要があります。

This sample text shows how to introduce a *new concept*.

19.9.2. 強調

  • 新しい概念ではない重要な用語を強調するには、その用語を二重のアスタリスク（**）で囲んで太字で記述します。

  • これは控えめに使いましょう！多用すると、読者には怒鳴っていたり見下しているように見えることがあります。

This sample text shows how to use **emphasis** in a sentence. Include the
punctuation mark if it is followed by a **comma,** or at the **end of the
sentence.**

19.9.3. 画像

  • 画像を追加する場合は、レッスンファイルの隣にある img フォルダに保存します。

  • 文書にそれを入れるにはこのようにします:

    .. figure:: img/image_file.extension
   :align: center

  • 画像マークアップの上方および下方の空行を残すことを忘れないでください。

19.9.6. 等幅テキストを使う

  • ユーザーが入力する必要のあるテキスト、パス名、またはテーブルや列の名前などのデータベース要素の名前を書いているときは、それを 等幅テキスト で記述する必要があります。例えば:

    Enter the following path in the text box: ``path/to/file``.

19.9.7. ラベルするGUI項目

  • GUIの項目、ボタンなど、を参照している場合は、 GUIラベルフォーマット の中にその名前を書く必要があります。例えば:

    To access this tool, click on the :guilabel:`Tool Name` button.

  • これは、ユーザーがボタンをクリックする必要なしに、ツールの名前を言及している場合にも適用されます。

19.9.9. 注を追加する

  • レッスンの流れの一部とすることが容易でない余分な詳細を説明するために、テキストに注を加えることが必要になる場合があります。これがそのマークアップです:

    [Normal paragraph.]

.. note:: Note text.
  New line within note.

  New paragraph within note.

[Unindented text resumes normal paragraph.]

19.9.10. 後援/原作者注を追加する

スポンサーに代わって新しいモジュール、レッスンまたはセクションを記述する場合は、スポンサーが希望する短いスポンサーメッセージを含める必要があります。これはスポンサーの名前を読者に通知しなければならず、そのスポンサーが主催するモジュール、レッスンやセクションの見出しの下に表示されなければなりません。しかし、それはスポンサーの会社の広告であってはいけません。

スポンサーに代わってではなく、自身の能力で自発的にモジュール、レッスン、またはセクションを書いた場合は、執筆したモジュール、レッスンやセクションの見出しの下に原作者注を入れることができます。これは、 この[モジュール/レッスン/セクション]は[著者名]による寄稿です という形を取る必要があります。それ以上のテキストや連絡先などは追加しないでください。そのような詳細は、追加した部分の名前と一緒に、前文の「寄稿者」セクションに追加されるべきです。機能強化、修正および/または追加を行っただけの場合は、編集者として自分自身をリストします。

19.10. ありがとうございました！

このプロジェクトに貢献していただきありがとうございます！そうすることで、QGISはユーザーからより利用しやすくなり、全体としてQGISプロジェクトに価値を付加しています。