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

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

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

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

19.2. マニュアルの形式

このマニュアルは、 スフィンクスreStructuredText マークアップ言語を使用するPythonの文書作成機能、を使用して書かれています。これらのツールを使用する方法については、それぞれのサイトからご利用可能です。

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

  • 新しいモジュールを追加するには、最初に新しいモジュール名を持つ新しいディレクトリ( qgis-training-manual ディレクトリのトップレベルのすぐ下)を作成します。

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

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

    .. toctree::
       :maxdepth: 2
    
    
       foreword/index
       introduction/index
    

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

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

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

  • 新しいモジュールの独自のインデックスファイルを開きます( [module name]/index.rst )。

  • ページの上部に沿って、80個のアスタリスク( * )の行を書きます。これは、モジュールの見出しを表します。

  • これに続けて 、モジュールの名前が続くマークアップの語句 |MOD| (「モジュール」の略)を含む行を書きます。

  • もう一度80個のアスタリスクの行を書いてこれを終えます。

  • この下に空白行を残します。

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

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

    .. toctree::
       :maxdepth: 2
    
    
       lesson1
       lesson2
    

    ...ここで、lesson1lesson2 などは、計画された授業の名前です。

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

*******************************************************************************
|MOD| Module Name
*******************************************************************************

Short paragraph describing the module.

.. toctree::
   :maxdepth: 2


   lesson1
   lesson2

19.4. レッスンを追加する

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

  • モジュールディレクトリを開く

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

  • 計画された授業の名前が、上で示されるように、 toctree ディレクティブ下に表示されていることを確認してください。

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

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

注釈

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

  • レッスンの書き込みを開始するには、マークアップの語句 |LS| を書き、その後ろにレッスン名を書きます。

  • 次の行に、80個の等号( = )の行を書き込みます。

  • この後に空行を残します。

  • 授業の意図された目的について短い説明を書きます。

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

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

    **The goal for this lesson:**
    
  • 簡単に言えば、このレッスンを完了することを意図し成果を説明します。

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

各レッスンは複数のセクションに細分化されます、それについては次に述べます。

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

セクションは2種類あります。「この通りに従ってください」と「自分でやってみよう」。

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

  • 「自分でやってみよう」セクションでは、読者自身が試す短い課題を与えます。これは通常表示または課題を完了するために、可能な場合に予想される結果を表示する方法を説明します、文書の最後に解答用紙のエントリに関連付けられています。

すべてのセクションでは、難易度が付属しています。簡単なセクションは |basic| 、適度は |moderate| 、および上級は |hard| で表されます。

19.5.1. 「この通りに従ってください」セクションを追加

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

  •  |FA| を書き込み、その後にスペースを入れてください(「この通りに従ってください」のため)。

  • (初回のみ大文字だけでなく、固有名詞のための大文字を使用)、別のスペースを残して、セクションの名前を書きます。

  • 次の行に、80個のマイナス/ダッシュ( - )の行を書き込みます。テキストエディタによってデフォルトのマイナス/ダッシュ文字が長いダッシュまたは他の文字で置き換えられないことを確認してください。

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

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

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

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

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

  • スペースを残し、その後 |TY| と書き込みます(「自分でやってみよう」のために)。

  • 次の行に、80個のマイナス/ダッシュ( - )の行を書き込みます。テキストエディタによってデフォルトのマイナス/ダッシュ文字が長いダッシュまたは他の文字で置き換えられないことを確認してください。

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

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

ほとんどの場合、このセクションで与えられた課題を完成する方法についての解答を提供したいと思うでしょう。そのためには、解答用紙にエントリを追加する必要があるでしょう。

  • まず、回答に一意の名前を決めます。この名前には、レッスン名と連番が入っているのが理想です。

  • この回答へのリンクを作成:

    :ref:`Check your results <answer-name>`
    
  • 解答用紙を開きます (answers/answers.rst)。

  • この行を書き込むことによって、「自分でやってみよう」セクションへのリンクを作成します:

    .. _answer-name:
    
  • 必要な場合、リンクや画像を使用して、割り当てを完了する方法の手順を書きます。

  • それを終了するには、この行を書き込むことによって、「自分でやってみよう」セクションに戻るリンクを含めます:

    :ref:`Back to text <backlink-answer-name>`
    
  • このリンクを動作させるために、「自分を試してみてください」セクションに、見出しの上に次の行を追加します:

    .. _backlink-answer-name:
    

文書を作成しながら、それ以外の場合はエラーが発生する可能性があり、上に示したこれらの線のそれぞれは、その上下の空白行を持たなければならないことに注意してください。

19.6. 結論を追加

  • レッスンを終了するには、80個のマイナス/ハイフン( - )の新しい行に続いて、 「結論」のための |IC| 語句を書きます。どのような概念がレッスンでカバーされているかを説明しながら、レッスンの結論を書きます。

19.7. [さらに読む]セクションを追加

  • このセクションは追加分です.

  • 80個のマイナス/ハイフン( - )の新しい行に続いて「さらに読む」のための語句 FR を書きます。

  • 適切な外部のウェブサイトへのリンクが含まれています。

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

  • 80個のマイナス/ハイフン( - )の新しい行に続いて、「次は」のための語句 |WN| を書きます。

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

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

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. 画像

  • 画像を追加する場合は、フォルダ _static/lesson_name/ に保存します。

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

    .. figure:: img/image_file.extension
       :align: center
    
  • 画像マークアップの上方および下方の空行を残すことを忘れないでください。

19.9.6. 等幅のテキストを使用して

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

    Enter the following path in the text box: :kbd:`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. 後援/原作者注を追加する

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

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

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

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