SE Can't Code

A Tokyo based Software Engineer. Not System Engineer :(

Sphinxで研修教材を作る.

仕事でプログラミング研修教材を作っている最中なのだが、その際に使ったSphinxが便利すぎた。SphinxPythonドキュメンテーション生成ツールで、簡易的なリッチテキストで文章書けたり、ドキュメント構成もindex.rstに生成したドキュメント名を追記していくだけで綺麗に取り込んでくれる。特にIPython-Notebookで研修の本番をハンズオン式で進めたり、Slideモードで発表したりという場合、作ったNotebookを下記のコマンド一発でrstに変換してくれるので、楽チンで複数の教材を一つのドキュメントに集約することができる。

$ ipython nbconvert [iPython-Notebookファイル] --to rst


rstファイルを生成した後は、HTMLにmakeしてあげればサーバー上で公開して誰でも閲覧できるようになる。
PythonOSSのドキュメントの多くはSphinxで作られたりしているが、GitHub.io上に載せることもコマンドで簡単に出来るのでこれはかなりオススメ。


なお、簡易的なSphinxの使い方は下記になる。

Step1.

Do the usual below command:

$ sphinx-quickstart

Step2.

In the source folder create an IPython notebook, say hello.ipynb

Step3.

Use nbconvert to export the notebook as a rst file.

$ipython nbconvert hello.ipynb --to rst

Step4.

Add the newly generated rst to your toctree. In my case, for demo purposes, I added it to index.rst. So, the contents of my index.rst look as follows:

vi index.rst

Edit below:

.. sphinx_ipynb documentation master file, created by
   sphinx-quickstart on Thu May  8 11:31:26 2014.
   You can adapt this file completely to your liking, but it should at least
   contain the root toctree directive.

Welcome to sphinx_ipynb's documentation!
========================================

Contents:

.. toctree::
   :maxdepth: 2

   hello
   howto



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

* Index
* Module Index
* Search Page
NB: here howto corresponds to the rendering of the current page.

Step5.

The usual sphinx stuff for building html. From the main sphinx folder:

$ make html

If everything goes right, you should have your html in build/html.

Remove all ads