4
Help us understand the problem. What are the problem?

More than 1 year has passed since last update.

posted at

updated at

ドキュメント作成ツールSphinxに入門する

はじめに

本エントリで説明すること

  • Python製のドキュメント作成ツール「Sphinx」の導入から簡単なドキュメント生成まで
  • ホットリロードするモジュール「sphinx-autobuild」のインストールと使い方
  • テーマの変更方法

本エントリで説明しないこと

  • python3とpipのインストール方法
  • reStructuredTextについての細かい説明
  • MkDocsのような他のドキュメント作成ツールとの比較
  • Sphinxの細かいオプション等

前提

  • python3系をインスールしていること

筆者の環境

  • macOS Catalina 10.15.3
  • Python 3.7.4

venvでSphinx用の仮想環境を作成する

Sphinx用の仮想環境のディレクトリを作成します。
ディレクトリ名は任意です

$ mkdir sphinx

作成したディレクトリに移動し、仮想環境を作成します
仮想環境名はここではsphinx-venvとしておきます。

$ cd sphinx
# 「python3 -m venv 仮想環境名」とすることで仮想環境を作成できます。
$ python3 -m venv sphinx-venv

仮想環境のディレクトリに移動し、仮想環境を有効にする

$ cd sphinx-venv
$ source bin/acitvate

pipでsphinxをインストールする

$ pip install sphinx

sphinxのプロジェクトを作成する

sphinx-quickstartを打つと、ズラズラとメッセージが流れて、対話的に何個か聞かれます。
ひとまず特にこだわりがなければ、下記のように設定すればよいと思います。

$ sphinx-quickstart
> ソースディレクトリとビルドディレクトリを分ける(y / n) [n]:y
> プロジェクト名: test-project
> 著者名(複数可): test-author
> プロジェクトのリリース []: 1.0.0
> プロジェクトの言語 [en]: ja

私の実行環境では、上記の通りに日本語で聞かれましたが、
環境によっては下記のように英語で聞かれます。

$ sphinx-quickstart
> Separate source and build directories (y/N) [n]:y
> Project name: test-project
> Author name(s): test-author
> Project version []: 1.0.0
> Project language [en]: ja

htmlファイルを生成する

まずはデフォルト状態で、htmlファイルを生成します。
htmlファイルを生成するには、Makefileがある場所で以下のようにコマンドを打ちます

$ make html

これで、buildディレクトリ以下にindex.htmlというファイルが生成されますので、
任意のブラウザで表示させてください。

コンテンツを追加する

Sphinxでは、コンテンツを追加するために、

  • 新しくファイルを作成し、
  • トップページに登録する

必要があります。

新しくファイルを作成する

「source」配下に適当な名前のファイルを作成します。
ここでは、ファイル名を「test.rst」とします。

適当に中身を書きます。

test.rst
===================
ここにタイトルを入れる
===================

大見出しを入れる
---------------
- 箇条書きです
- 箇条書きです

トップページに登録する

「source」配下にある「index.rst」がトップページになっています。
このファイルを編集し、先程作成した「test.rst」を登録します。
編集は以下のように、ファイル名と同じ名前を追記してください。

index.rst(編集前)
.. toctree::
   :maxdepth: 2
   :caption: Contents:

index.rst(編集後)
.. toctree::
   :maxdepth: 2
   :caption: Contents:

   test

ここで、もう一度、「make html」を実行すると、トップページに
「ここにタイトルを入れる」がリンク付きで表示されるようになります。
こちらのリンクをクリックすると、test.rstに記載した内容を見ることができます。

【おまけ】ホットリロードできるようにする

Sphinxでは通常、ドキュメントを編集した後、「make html」と打ち、ブラウザをリロードし直す必要があります。これは地味に面倒ですので、ドキュメントを編集したら、自動でhtmlファイルを生成し、自動でリロードが掛かるようにします。

$ pip install sphinx-autobuild

インストール後は、「Makefile」があるディレクトリで以下のコマンドを打ちます。

# sphinx-autobuild [xxx.rstがあるディレクトリ] [htmlファイルが生成されるディレクトリ]
# 本エントリでは、以下のようになります
$ sphinx-autobuild source build

すると、ローカルでサーバが起動しますので、URL(http://localhost:8080)をブラウザで表示すると、作成されたhtmlファイルを閲覧できます。

【おまけ】テーマを変える

「source」ディレクトリ配下にある「conf.py」の下の方に以下の記述があります。

conf.py
html_theme = 'alabaster'

'alabaster'のところを書き換えることで、テーマを変えることができます。
なお、'alabaster'はデフォルトのテーマになっています。

Sphixでは標準の以下のテーマが用意されています。

  • alabaster
  • default
  • sphinxdoc
  • scrolls
  • agogo
  • nature
  • pyramid
  • haiku
  • traditional
  • bizstyle

サードパーティ製のテーマを設定することも可能です。
例えば、マテリアルデザインのテーマを設定したい場合は以下のようにテーマをインストールします。

$ pip install sphinx-theme-material

テーマをインストールしたら、conf.pyを以下のように設定します。
設定後、テーマがマテリアルデザインに変わっています。

conf.py
html_theme = 'material'
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Sign upLogin
4
Help us understand the problem. What are the problem?