CentOS 7でSphinxを使用して複数の形式でドキュメントを作成する

• 前提条件
• ステップ1：システムを更新する
• ステップ2：pipとSphinxをインストールする
• ステップ3：ドキュメントの基本構成をセットアップする
• ステップ4：ドキュメントの階層を構築する
• ステップ5：上記で指定したソースファイルを作成する
• ステップ6：ドキュメントのHTMLバージョンを出力する

Sphinxは、技術者やライターがPythonをベースにした便利なツールであり、さまざまな形式のエレガントで完全に機能するドキュメントを簡単に作成できます。Sphinxでは、最初にreStructuredText（軽量のマークアップ言語）を使用してドキュメントを作成し��HTML、LaTeX、PDF、ePubなどを含む複数の形式で出力を取得できます。

このチュートリアルではSphinx、Vultのプラットフォーム上のCentOS 7 x64インスタンスにインストールして使用するプロセスについて説明します。

前提条件

• CentOS 7 x64インスタンス。
• sudoのユーザー。

ステップ1：システムを更新する

sudo yum update
sudo shutdown -r now

ステップ2：pipとSphinxをインストールする

sudo yum install -y python-devel python-setuptools python-pip
sudo pip install --upgrade pip
sudo pip install -U Sphinx

ステップ3：ドキュメントの基本構成をセットアップする

の使用を開始する前にSphinx、Sphinxすべてのドキュメントを実行して保存するソースディレクトリを指定する必要があります。使用するディレクトリを作成したら、必要な基本構成sphinx-quickstartを初期化Sphinxして作成するを実行できます。

sphinx-quickstart プロジェクトの側面を決定する質問を表示するセットアップウィザードに似ています。

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

ステップ4：ドキュメントの階層を構築する

デフォルトでは、sphinx-quickstartウィザードはいくつかのディレクトリとファイルを作成します。

_build           # The directory for containing Sphinx output
conf.py          # The file containing your project configurations
index.rst        # The master file containing the hierarchy of your documentation
make.bat         # A Windows command file
Makefile         # A file necessary for running the make command
_static          # The directory for static files, including custom stylesheets, pictures, etc.
_templates       # The directory for custom templates

index.rstドキュメントの階層が含まれているマスターファイルを見てみましょう。つまり、目次ツリーまたはtoctreeです。

テキストエディタで開きます。

vi index.rst

ファイルを確認すると、というセクションがありtoctreeます。*.rstドキュメントに他のソースファイル（）がある場合は、toctreeセクションでそれらを指定する必要があります。.. toctree ::：maxdepth：2

   introduction
   chapter1
   chapter2
   chapter3
   more

次のことが不可欠です。

• 入力の上に空白行を残します。
• ソースファイルの末尾に.rst。を付けないでください。
• ソースファイルをそれぞれの順序で配置します。
• 行ごとに1つのファイル名のみを使用します。
• でファイル名をインデントします:maxdepth: 2。

変更が完了したら、ファイルを保存してテキストエディターを終了します。

ESC
:!wq

ステップ5：上記で指定したソースファイルを作成する

ソースファイルは、以前にで指定されたものと一致する名前で作成する必要がありますindex.rst。そうでない場合、最終出力に含まれません。

すべてのソースファイルはと互換性がある必要がありますreStructuredText markup language。詳細については、reStructuredText Primerを参照してください。

ステップ6：ドキュメントのHTMLバージョンを出力する

ドキュメントの作成が完了したらHTML format 、次のコマンドを実行して作業を出力できます。

make html

出力は./\_build/html、Webブラウジングでファイルを表示するために必要なすべてを含むディレクトリに保存されます。

これでチュートリアルは終了です。