ドキュメントを書く

新しいドキュメントの追加

If any new documentation files are added the need to be added to the toctree for that section. This is usually found in the index.rst file for the directory you need to add your documentation to. 例えばcommunity/ ディレクトリの中で、index.rstファイルは以下のようなtoctreeを含みます:

それぞれは.rst拡張子を持つことを意味します。各ファイルはSphinxを使ってビルドされる時に別個のHTMLファイルにコンパイルされるでしょう。

モジュールドキュメントの追加

tocreeへの追加に加えて、モジュールはmodules/index.rst内の大きな表に追加される必要があります。これは3つのカラムを持ち、モジュールの言語はドキュメントのための.rst ファイルを示すための:doc: ディレクティブを使う必要があります。この説明は2,3の単語の概要でなければなりません。リポジトリは、可能であればgithub あるいは bitbucket ディレクティブが使われるべきです。あるいはそれ以外のものが使われた場合はリポジトリへのリンクであるべきです。

モジュールはアルファベット順に維持してください。これにより他の人が見つけるのが楽になります。

reStructuredText Basics

これらはreStructuredTextファイルを書くための基本です。更に詳しい情報は、Sphinx独自のドキュメント および Quick reStructuredTextを見ることをとてもお勧めします。何が可能なのかの詳細な概論については、reStructuredText 仕様を見てください。

Pythonのように、内容のブロックは一般的に空白のインデントによって入れ子になっています。例えば:

.. note::

   This is a note!
   It is multi-line!

注意

This is a note! It is multi-line

インラインのMarkup

基本のテキスト整形のために使うことができる様々なインラインmarkupがあります。例えば:

* *emphasis*
* **bold**
* ``literal``
* :sub:`subscript`
* :sup:`superscript`
  • emphasis
  • bold
  • literal
  • subscript
  • superscript

バレットとリスト

バレットと順番ありのリストはとても簡単です。

* バレットの点はアスタリスクです

  * は入れ子にすることができます
  * しかし親のリストを続けるには他の空白行が必要です

* そして、親のリストを続けるには他の空白行が必要です
  • バレットの点はアスタリスクです
    • 入れ子にすることができます
    • しかし親のリストを続けるには他の空白行が必要です
  • そして、親のリストを続けるには他の空白行が必要です
#. 自動生成の数字リスト

   #. 入れ子にすることもできます

#. 親の

1. 指定数値リストを続けることも
2. できます
  1. 自動生成の数字リスト
    1. 入れ子にすることができます
  2. 親の
  1. 指定数値リストを続けることも
  2. できます

Headings

Headings are signified by using characters on the line below to underline them. Different styles signify level. ヘッディングはwikiのための内容の表をビルドするために自動的に使われます:

Heading
=======

SubHeading
----------

More depth
^^^^^^^^^^

表

表を作るには2つの方法があります。Gridテーブルとシンプルテーブルです。

Grid テーブルはテーブルを設計するためにASCIIアートを使います。以下は例です:

+-----------+----------+----------+
| Column 1  | Column 2 | Column 3 |
| Multiline |          |          |
+===========+==========+==========+
| item 1    | stuff    | nonsense |
+-----------+----------+----------+
| item 2    | horizontal span     |
+-----------+----------+----------+
| item 3    | vertical | is       |
+-----------+ span     | possible |
| item 4    |          | too.     |
+-----------+----------+----------+
Column 1 Multiline Column 2 Column 3
item 1 stuff nonsense
item 2 horizontal span
item 3 vertical span is possible too.
item 4

一方でシンプルテーブルは柔軟性がありませんが、作りやすいです:

======== ======== ========
Column 1 Column 2 Column 3
======== ======== ========
item a   item b   item c
item d   item e   item f
======== ======== ========
Column 1 Column 2 Column 3
item a item b item c
item d item e item f

構文のハイライト

Sphinxはコードブロックの構文をハイライトすることができます。例えば:

.. code-block:: c

   #include <stdio.h>

   int main(void)
   {
     printf("Hello World!");
     return 0;
   }

#include <stdio.h>

int main(void)
{
  printf("Hello World!");
  return 0;
}

NGINX設定ファイルのための構文ハイライトもあります。以下は行番号付きのこの例です:

.. code-block:: nginx
   :linenos:

   server {
       listen          80;
       server_name     domain.com *.domain.com;
       return          301 $scheme://www.domain.com$request_uri;
   }

   server {
       listen          80;
       server_name     www.domain.com;

       index           index.html;
       root            /home/domain.com;
   }

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
server {
    listen          80;
    server_name     domain.com *.domain.com;
    return          301 $scheme://www.domain.com$request_uri;
}

server {
    listen          80;
    server_name     www.domain.com;

    index           index.html;
    root            /home/domain.com;
}

参照

Pygments でも - A利用可能な構文ハイライトの種類のデモです。

脚注

脚注の最も簡単な形式は、テキスト中に[1]_を使い、以下のようにページの一番下のセクションに[1]を使って生成することができます:

.. rubric:: Footnotes

.. [1] Like this

以下が生成されます:

脚注

[1]Like this

注意、警告、Todoと参照

注意、警告およびtodoは全て似たような形式です。描画時にwikiはtodoを隠すように設定されています:

.. note::
   これは注意です

.. warning::
   これは警告です

.. todo::
   これはtodoです

.. seealso::
   これは参照です

以下が生成されます:

注意

これは注意です

警告

これは傾向です

参照

これは参照です

NGINX Wiki 固有のルール

このwikiでドキュメントを生成するのを手助けするために追加された2,3の特別な役割があります。

:icon:

icon役割はテキスト中にFont Awesome アイコンを使うことができます。Simply use as described in the Font Awesome documentation but without the fa prefix and the options comma separated. 例えば:

A globe example: :icon:`globe`

A globe example:

:github:

GitHubパスに基づいたリンクへのGitHubアイコンを生成します。例えば:

:github:`nginxinc/nginx-wiki`

nginxinc/nginx-wiki

:bitbucket:

Bitbucketパスに基づいたリンクへのBitbucketアイコンを生成します。例えば:

:bitbucket:`nginx-goodies/nginx-sticky-module-ng`

nginx-goodies/nginx-sticky-module-ng