Sphinx 導入

仕事での文章作成にSphinxを導入したので、備忘録として書いておきます。

Sphinxの導入

Macで主にHomebrewを使用してる場合の例です。

SphinxはPythonで記述されているため、Pythonの環境が必要です。Pythonの導入については、以下の記事を参照ください。

• NeoVimの導入

Sphinxの導入です

$ sudo pip install -U Sphinx

その他、テーマなどを使用する場合は別途導入が必要ですが、ここでは省きます。

Sphinxでの文書作成

まずはフォルダを掘って、以下のコマンドを実行します。

$ sphinx-quickstart

するとウィザード的に色々と質問されますが、答えていくとテンプレート的なものを作成してくれます。デフォルトでは、index.rstがメインの文書となっています。

以下がそのサンプルです。

```markdown:index.rst 怪人と少年探偵 |release| =======================================

.. toctree:: :maxdepth: 2 :numbered: :caption: 目次：

chapter1 chapter2 chapter3

Indices and tables

• :ref:genindex
• :ref:modindex
• :ref:search

１行目がタイトルです。目次を生成するコマンドが並び、次に`chapter1`などとあるのは、分割して記述した`chapter1.rst`などのファイルを読み込むための記述です。

```markdown:chaper3.rst
----------------------------------------
顔の動かない男
----------------------------------------
デパートの洋服売り場の人形にばけて、宝石をぬすんだ怪人は、店員におわれて、こんどはデパートの支配人にばけ、店員たちをごまかして、そのまま、おおぜいのお客さんにまぎれこんで、デパートから、にげだしてしまいました。

　新聞はこの事件を、「人形怪盗あらわる」という見出しで、でかでかと書きたて、東京じゅうのひょうばんになりました。

　それから三日めの夕方近いころです。少年探偵団の井上一郎《いのうえいちろう》少年とポケット小僧《こぞう》が、ちょっと用事があって、練馬区《ねりまく》のはずれのさびしい町をあるいていました。

　少年探偵団というのは、名探偵明智小五郎の少年助手の小林君が団長となって、小学校の上級生や中学生でつくっている少年探偵の組合で、これまでにも、明智探偵をたすけて、たくさんのてがらをたてているのです。

記法的にはMarkdownに似ていますね。reStructuredTextという記法らしいです。

文書が作成できたら、make htmlとすればHTML化された文書を作成してくれます。他にLatex, PDF, ePubなどの形式をサポートしています。

目次や索引、HTML形式であれば検索ページも作成してくれます。

技術系の文書を作成するのであれば、多くの形式に変換可能ですので非常に便利なツールになると思います。