Sphinxでドキュメント作成 - github.ioでの公開まで

Sphinx とは

Python製のドキュメント生成ツール。 特徴としては以下の通り。

  • reStructuredTextで記述する(プラグインの導入によりMarkdownも可)
  • ドキュメントを複数ファイルに分けて管理することができる
  • 実体はプレーンテキストなのでGit等でバージョン管理可能
  • ソースコードとともにバージョン管理が可能
  • 図表や数式の記述も可能

最近ドキュメントの作成を依頼されるとまずsphinxが思い浮かぶ。
それくらい気に入っているツール。

インストール

それでは早速インストール

pip install sphinx

これだけ。

プロジェクトの作成

sphinx-quickstart

このコマンドを実行すると、以下の項目について対話的に聞かれます。 目的と内容にあった選択をしましょう。

  • ドキュメントのルートパス
  • ソースと、ビルド結果のフォルダを完全に分けるかどうか。
  • Sphinxの作るシステムディレクトリの名前の先頭に付く接頭辞。
  • プロジェクト名と著者名
  • プロジェクトのバージョン
  • ソースファイルのデフォルトの拡張子
  • ドキュメントのトップページのファイル名
  • 各種拡張機能をインストールするかどうか。

基本デフォルトで問題ないと思います。 これを実行すると、以下のような構成のプロジェクトディレクトリが生成されます。

project_dir
├── Makefile
├── _build
├── _static
├── _templates
├── conf.py
├── index.rst
└── make.bat

ドキュメントの生成

先ほどのsphinx-quickstartで生成されたMakefileにはドキュメントを生成するためのコマンドが書かれています。 html形式で出力したい場合、以下のようにコマンドを打ちます。

make html

すると、_buildディレクトリ以下のhtmlディレクトリ内にhtml群が生成されます。

project_dir
├── Makefile
├── _build
│   ├── doctrees
│   │   ├── environment.pickle
│   │   └── index.doctree
│   └── html
│       ├── _sources
│       ├── _static
│       ├── genindex.html
│       ├── index.html
│       ├── objects.inv
│       ├── search.html
│       └── searchindex.js
├── _static
├── _templates
├── conf.py
├── index.rst
└── make.bat

試しにindex.htmlをブラウザで開いてみると、以下のような表示となります。 f:id:kimoppy126:20181008133833p:plain

デフォルトでは、

  • 目次(index.html
  • 索引(genindex.html
  • 検索ページ(search.html
  • モジュール索引(modindex

が用意されており、下3つは目次(index.html)から飛べるようになっています。

. test_project documentation master file, created by
   sphinx-quickstart on Tue Oct  9 00:23:36 2018.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to test_project's documentation!
========================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:



Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Markdownの対応

一般的にはreStructuredText記法よりもMarkdown記法のほうが使われているかと思います。
Markdownへの対応は数分で終わるのでやってしまいましょう。

まず、Markdown記法の読み込みに使用するパッケージをインストールします。

pip install recommonmark

次に、Markdownを読み込めるようにconfファイルで指定してやります。 以下のように変更します。

conf.py

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
source_suffix = ['.rst', '.md']
# source_suffix = '.rst'

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

source_suffix = ['.rst', '.md']

ページの追加

ではいよいよオリジナルのページを追加していきましょう。
といってもこれまた簡単で、index.rstに認識させてあげれば project_dir中どこにおいてもオーケーです。

例えば、以下のような階層構造を持たせた(test > project1.md, project2.md)
Markdown形式のファイルを用意して、

project_dir
└── test
    ├── project1.md
    └── project2.md

それぞれ以下のようにMarkdown記法で記述します。 project1.md

# test1

これはテストです。

これはtestです。

project2.md

# テスト2

これもテストです

## テスト2小見出し1

- あ
- い
- う

## テスト2小見出し2

そしてmake html

make html

これを実行すると、以下のようにhtmlが階層構造を保ったまま出力されます。

project_dir
├── _build
│   └── html
│       └── test
│           ├── project1.html
│           └── project2.html

出力結果 f:id:kimoppy126:20181009094446p:plain

ちゃんとMarkdownも反映されてます。

f:id:kimoppy126:20181009095935p:plain

github.ioで公開

以下のサイトがとっても丁寧
https://sky-joker.github.io/github_sphinx_example/#docs

試しに公開してみたがなぜかCSSが反映されない。。
https://nkimoto.github.io/sphinx_test/

f:id:kimoppy126:20181009104314p:plain

原因わかる方いたら教えて下さいまし。