新しいドキュメントファイルが追加されると、その章についてのtoctree が追加される必要があります。これは一般的にドキュメントが追加される必要があるディレクトリについてのindex.rst
の中で見つかります。例えばcommunity/
ディレクトリの中で、index.rst
ファイルは以下のようなtoctreeを含みます:
それぞれは.rst
拡張子を持つことを意味します。各ファイルはSphinxを使ってビルドされる時に別個のHTMLファイルにコンパイルされるでしょう。
toctreeに追加することに加えて、モジュールをmodules/index.rst
内の大きな表に追加される必要があります。これは3つのカラムを持ち、モジュールの言語はドキュメントのための.rst
ファイルを示すための:doc:
ディレクティブを使う必要があります。この説明は2,3の単語の概要でなければなりません。リポジトリは、可能であればgithub
あるいは bitbucket
ディレクティブが使われるべきです。あるいはそれ以外のものが使われた場合はリポジトリへのリンクであるべきです。
モジュールはアルファベット順に維持してください。これにより他の人が見つけるのが楽になります。
これらはreStructuredTextファイルを書くための基本です。更に詳しい情報は、Sphinx独自のドキュメント および Quick reStructuredTextを見ることをとてもお勧めします。何が可能なのかの詳細な概論については、reStructuredText 仕様を見てください。
Pythonのように、内容のブロックは一般的に空白のインデントによって入れ子になっています。例えば:
.. note::
これは注記です!
複数の行です!
注意
これは注記です!複数の行です!
基本のテキスト整形のために使うことができる様々なインラインmarkupがあります。例えば:
* *emphasis*
* **bold**
* ``literal``
* :sub:`subscript`
* :sup:`superscript`
literal
バレットと順番ありのリストはとても簡単です。
* バレットの点はアスタリスクです
* は入れ子にすることができます
* しかし親のリストを続けるには他の空白行が必要です
* そして、親のリストを続けるには他の空白行が必要です
#. 自動生成の数字リスト
#. 入れ子にすることもできます
#. 親の
1. 指定数値リストを続けることも
2. できます
内部リンクと、可能であれば外部リンクがあります。
.. _reference-location:
`NGINX Webサイト <https://www.nginx.com/>`_
他のドキュメントへのリンク: :doc:`index`
:ref:`abritrary reference <reference-location>`へのリンク
他のドキュメントへのリンク: Contributing to NGINX
abritrary referenceへのリンク
表題はすぐ下の行の下線で強調するための文字を使って示すことができます。異なる形式はレベルを表します。表題は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は全て似たような形式です。描画時にwikiはtodoを隠すように設定されています:
.. note::
これは注意です
.. warning::
これは警告です
.. todo::
これはtodoです
.. seealso::
これは参照です
以下が生成されます:
注意
これは注意です
警告
これは傾向です
参照
これは参照です
この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`
:bitbucket:
¶Bitbucketパスに基づいたリンクへのBitbucketアイコンを生成します。例えば:
:bitbucket:`nginx-goodies/nginx-sticky-module-ng`