Help us understand the problem. What is going on with this article?

sphinx でドキュメント作成からWeb公開までをやってみた


今回、ドキュメントをソースコードと同じ場所にまとめておきたいと思い、sphinx を使ってドキュメント作成を行なったので、その内容をまとめておきます。

sphinx とは?

sphinx とは Python 製のドキュメント生成ツールです。
reST(reStructuredText) 記法でドキュメントを作成できるので、マークダウンに慣れている人には非常に使いやすいと思います。
Python の公式ドキュメントも sphinx で作成されているそうです。


pip install で sphinx を install します。

$ pip install sphinx


人が作った、sphinx のプロジェクトを見ると、いろんなディレクトリがあって、ややこしそうだなーと思っていたのですが、


$ mkdir test_document
$ cd test_document

では、sphinx-quickstartコマンドで sphinx のプロジェクトを作成します。
下記のように色々質問されますが、基本的には Enter で OK です。

  • Separate source and build directories (y/n) [n]: y
  • Project name: test_document
  • Author name(s): kinpira
  • Project version []: 1.0.0
  • Project language [en]: ja
$ sphinx-quickstart
Welcome to the Sphinx 1.6.4 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Enter the root path for documentation.
> Root path for the documentation [.]:
# ↑ドキュメントのルートパス省略時は今の場所

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y
# ↑ソースと、ビルド結果のフォルダを完全に分けるかどうか。
# デフォルトはソースのフォルダ内に_buildディレクトリができる。

Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]:
# ↑Sphinxの作るシステムディレクトリの名前の先頭に付く接頭辞。デフォルトは'_'

The project name will occur in several places in the built documentation.
> Project name: test_document
> Author name(s): kinpira
# ↑プロジェクト名と著者名。

Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1.  If you don't need this dual structure,
just set both to the same value.
> Project version []: 1.0.0
> Project release [1.0.0]:
# ↑プロジェクトのバージョン。

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
> Project language [en]: ja

The file name suffix for source files. Commonly, this is either ".txt"
or ".rst".  Only files with this suffix are considered documents.
> Source file suffix [.rst]:
# ↑ソースファイルのデフォルトの拡張子。デフォルトは.rst。.txtも良く使われる。

One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]:
# ↑ドキュメントのトップページ(マスター)のファイル名(拡張子なし)。デフォルトは'index'

Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/n) [n]:
# ↑各種拡張機能をインストールするかどうか。必要なら後で追加できます。

Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/n) [n]:
> doctest: automatically test code snippets in doctest blocks (y/n) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]:
> coverage: checks for documentation coverage (y/n) [n]:
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]:
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
> ifconfig: conditional inclusion of content based on config values (y/n) [n]:
> viewcode: include links to the source code of documented Python objects (y/n) [n]:
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
> Create Makefile? (y/n) [y]:
> Create Windows command file? (y/n) [y]:
# ↑ビルド用のMakefileとバッチファイルを作るかどうか。デフォルトはY。作りましょう。

Creating file ./source/
Creating file ./source/index.rst.
Creating file ./Makefile.
Creating file ./make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file ./source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

しかし、この段階ではまだ HTML ファイルは存在していません。
HTML はまた別途コマンドを叩く必要があります。

$ tree
├── Makefile
├── build
├── make.bat
└── source
    ├── _static
    ├── _templates
    └── index.rst


では、早速 HTML を作成してみます。
make html コマンドで作成できます。

$ make html
Running Sphinx v1.6.4
build succeeded.


$ tree
├── Makefile
├── build
│   ├── doctrees
│   │   ├── environment.pickle
│   │   └── index.doctree
│   └── html
│       ├── _sources
│       │   └── index.rst.txt
│       ├── _static
│       │   ├── ajax-loader.gif
│       │   ├── alabaster.css
│       │   ├── basic.css
│       │   ├── comment-bright.png
│       │   ├── comment-close.png
│       │   ├── comment.png
│       │   ├── custom.css
│       │   ├── doctools.js
│       │   ├── down-pressed.png
│       │   ├── down.png
│       │   ├── file.png
│       │   ├── jquery-3.1.0.js
│       │   ├── jquery.js
│       │   ├── minus.png
│       │   ├── plus.png
│       │   ├── pygments.css
│       │   ├── searchtools.js
│       │   ├── translations.js
│       │   ├── underscore-1.3.1.js
│       │   ├── underscore.js
│       │   ├── up-pressed.png
│       │   ├── up.png
│       │   └── websupport.js
│       ├── genindex.html
│       ├── index.html
│       ├── objects.inv
│       ├── search.html
│       └── searchindex.js
├── make.bat
└── source
    ├── _static
    ├── _templates
    └── index.rst

build 以下に HTML や css や js などが作成されていることがわかります。
これは、source 以下にある index.rst を元に HTML が作成されています。
なので、 source 以下に reST ファイルを作成し、 make html で HTML を作成する形になります。

デザインテーマは の設定を変える事で変更できます。


変更するには の html_theme の値を変更します。

$ pip install cloud-sptheme

conf のテーマを変更します。

html_theme = 'cloud'

では、もう一度 make html を実行します。

$ make html
Running Sphinx v1.6.4
loading translations [ja]... done
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
preparing documents... done
writing output... [100%] index
Exception occurred:
  File "/Users/xxxxxxxxxxx/.virtualenvs/doc/lib/python2.7/site-packages/sphinx/", line 200, in get_source
    raise TemplateNotFound(template)
TemplateNotFound: about.html
The full traceback has been saved in /var/folders/4m/j1vd525s6fv_2zsfrt47mtmwkk47dm/T/sphinx-err-aUkTiY.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <>. Thanks!
make: *** [html] Error 1

これは に元々設定されていた、html_theme = 'alabaster' 独自の設定がconf に書かれているため、おきるエラーのようです。
どうやら、 html_sidebarsの設定がよくないらしいので、コメントアウトします。

# html_sidebars = {
#     '**': [
#         'about.html',
#         'navigation.html',
#         'relations.html',  # needs 'show_related': True theme option to display
#         'searchbox.html',
#         'donate.html',
#     ]
# }

そして、make htmlを叩くと、次はうまくいきました。
スクリーンショット 2017-10-20 17.49.28.png


ちなみに、フロー図とか描きたい人は、sphinxcontrib-seqdiag をインストールしておくと幸せになれます。

$ pip install sphinxcontrib-seqdiag

conf に設定追加
extensions = ['sphinxcontrib.seqdiag']




今回は source 以下に test ディレクトリを作成し、下記の用な test1.rst ~ test3.rst ファイルを追加します。

$ tree source/
├── _static
├── _templates
├── index.rst
└── test
    ├── test1.rst
    ├── test2.rst
    └── test3.rst


sphinx やってみた1

| 試しに、こんな感じのページを
| 作ってみる!

====== ================
ID      Value
====== ================
3      データ3
4      データ4
====== ================

.. seqdiag::

   seqdiag {
      A -> B[label = "test"];
      B -> C[label = "test"];
      A [description = "browsers in each client"];
      B [description = "web server"];
      C [description = "database server"];


次に TOP ページである index.rst に追加して、目次を作成します。

# index.rst
Welcome to test_document's documentation!

.. toctree::
   :maxdepth: 2
   :caption: OverView


.. toctree::
   :maxdepth: 2
   :caption: test3だけ


  • toctree : のブロックが大項目になります。
  • maxdepth : で目次に表示するのツリーの深さを指定できます。
  • caption : 大項目のタイトル
  • numbered : 目次に追加したい、ファイルの path を追記します。


では再度 make html を行い、ブラウザで確認してみたいと思います。

先ほど index.rst に指定した、toctree のブロックごとに別れている事がわかります。

スクリーンショット 2017-10-20 18.36.48.png

スクリーンショット 2017-10-20 18.37.22.png

github pages で web 公開してみる

github でリポジトリを作成する。
今回は sphinx_test リポジトリを作成しました。

次に /build/html 以下に移動し、そこで github にでている指示通り git init から push までを行います。

$ cd /build/html
$ git init
$ git add .
$ git commit -m "first commit"
$ git remote add origin
$ git push -u origin master

ちなみに、このままだと CSS などが有効にならずに、表示が崩れてしまうため、先に .nojekyll ファイルを作成し、 gh-pages ブランチに切り替えて起きます。

$ git checkout -b gh-pages
$ touch .nojekyll
$ git commit -a -m "Add .nojekyll"
$ git push origin gh-pages

guithub で公開設定を行う

guihub の sphinx_test リポジトリの settings ページに GitHub Pages という項目があるので、
gh-pages ブランチを選択して save します。
上部に URL が表示されるので、そこにアクセスするとページが表示されます。





今回やってみた通り、簡単に作成でき、web 公開ができるので、すごく便利でした。
あとは、ソースコードと一緒に git 上に置いておく事ができるのもメリットとして大きいと思います。

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