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

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

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

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

19.2. マニュアルの形式

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

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. 「この通りに従ってください」セクションを追加

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

  • スペースを置き、次に(「この通りに従ってください」の):kbd:|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プロジェクトに価値を付加しています。