reSt, Sphinxメモ

reSTructuredText

pip install docutilsすると rst2htmlでhtmlにできる。 rst2s5でhtmlスライドにできる

markdownと違う点

見出し

h1見出し

========
title 1
========

ここで、title1が上下の線より長いと怒られる。

h2

下だけ=

title 2
========

h3

ハイフンで囲む

-------
title 3
-------

h4

下だけハイフン

title 4
-------

h5やh6はない

ラインブロック

|で囲む

|ここの部分の |文章はそのまま |生の文字列になる

replace

.. |hoge| replace:: ほげ

と書いておくとほかの|hoge|がほげに変換される。いっぱいあるときは、別ファイルに書いておいて

.. include:: definition.txt

とする

リンク

外部リンク

markdownと違い、外部参照のリンクはドキュメントの末尾にまとめて書かれる。

ここでのポイントは、..と_

`Plone CMS`_ を試してみてください。これはすばらしいですよ！ Zope_ 上に作られています。

.. _`Plone CMS`: http://plone.org
.. _Zope: http://zope.org

末尾でなくともOK

`python <www.python.org>`_

内部リンク

.. _ex-hoge:

---------------
ほげほげ
---------------

このように、章や節の上に記述して定義する。

--------
他の場所
--------

ほげほげに関しては :ref:`ほげほげ<ex-hoge>` として任意のテキストで参照します。

ソースコードの記述

インラインリテラルは``を2つずつつける必要がある。

print("hoge") -> reST中では``print(“hoge”)``

インラインでない通常のリテラルは::の後に、インデントを入れることで記述可能

next paragraph is source code::
               #ここの空白は必須
    1 + 1

..code-block::を使ったほうが良いかも。htmlの例

..code-block::html
    :linenos:  # 行番号を表示

    <h1>hogehoge</h1>

外部ファイルをインクルードする場合は

 ..literalinclude::filename
    :linenos:
    :language: python
    :lines: 1, 3-5
    :start-after: 3
    :end-before: 5

テーブル

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

ただし、これは書くのが難しいのでcsvやListを使用する

.. csv-table:: Frozen Delights!
   :header: "Treat", "Quantity", "Description"
   :widths: 15, 10, 30

   "Albatross", 2.99, "On a stick!"
   "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
   crunchy, now would it?"
   "Gannet Ripple", 1.99, "On a stick!"


.. list-table:: Frozen Delights!
   :widths: 15 10 30
   :header-rows: 1

   * - Treat
     - Quantity
     - Description
   * - Crunchy Frog
     - 1.49
     - If we took the bones out, it wouldn't be
       crunchy, now would it?

ディレクティブ, directive

Sphinx拡張のものと、rst標準のものがある

toctree

章や節に番号を振りたいときは

.. toctree::
   :maxdepth: 2
   :numbered:

   overview
   design
   implementation

:glob:をtoctreeの下に追加するとglob表現で複数の対象を一括指定できる

画像

.. image:: gnu.png

で画像を表示できる。gnu.pngのところは、rstファイルからの相対パスや絶対パスも指定できる。 html出力すると、_staticのようなディレクトリにコピーされる。

note(ノートブロック)の表示

.. seealso:: This is a simple **seealso** note
.. note:: note that ...
..  warning:: be careful not to ...

脚注、footnote

[#]_を使用する

hogehoge [#f1]_.
.. [#f1] hogehogeに特に意味は無い

あるいは[1]のように普通に番号を振っても良い

引用

Sphinx拡張の機能

This Idea is originally from [Ref]_

.. [Ref] Book or article reference or url

TODO

.. todo:: ブロック図を描く

.. todolist::   #文書中の全てのTODOリストを集めて表示

よく使うSphinx拡張ディレクティブ

Sphinxについて

始める

sphinx-quickstart,以下のディレクトリとファイルを作成する

Makefile
_build
_static … CSSとか？
_templates　… htmlテンプレートの置場
conf.py … 設定ファイル。拡張モジュールのpathや言語の設定などをかける。
index.rst　…　ソースファイル
make.bat 途中で言語を聞かれるがjaを選択する

make latex,make latexpdf、make html等でrenderする.詳細はmake helpで

テーマの変更

Sphinx組み込みのテーマなら簡単。

html_theme = "classic"
html_theme_options = {
    "rightsidebar": "true",
    "relbarbgcolor": "black"
}

詳しくはこちら

Sphinx拡張

下で書いているもの以外にもdocstringをドキュメント中に組み込んだり、Graphviz、継承関係図、カバレッジなどを取り込むことができる

sphinx.ext.todo

rstファイルの中で

.. todo::という記法でtodoを作成できる
.. todolist::ディレクティブを使用すると、ドキュメント内のすべてのTODOをリストにして表示する

sphinx.ext.jsmath、Sphinx.ext.pngmath

それぞれjsMath(java script)、dvipngを利用して数式を表示する *現在はjsmathではなく、mathjax*を使う

mathjax

.. math::ディレクティブを使用できるようになる。その中ではlatex記法で書く。例

.. math:: e^{i\pi} + 1 = 0
    :label: euler

.. math::
    :label: quite

    (a + b)^2 &= (a + b)(a + b) \\
              &= a^2 + 2ab + b^2

:label:を付けると、数式にラベルと数式番号を付けることができ、:eq:を用いて参照することができる。例 :eq:`euler`

plnatuml

uml図が作れる

S6

スライドショーが作れる

作図

よく使いそうなのは

blockdiag
nwdiag
actdiag
seqdiag

くらい。継承関係図は別

継承関係図

大きく3つのやり方がある。

sphinx.ext.graphvizを使用して図を描く … graphviz::ディレクティブを使用する。抽象度が低い分単純な図しか書けない。
sphinxcontrib.plantumlを使用してJavaっぽい図を描く … pip install sphinxcontrib-plantumlでインストールしたのち、.. uml::ディレクティブを使用する。3に比べて自由な図をかける点にメリットがある。
sphinx.ext.inheritance_diagramを使用する。… ソースコードの状態が反映される。

ややこしいのだが、conf.py中ではsphinx.ext.inheritance_diagramと、アンダーバーを使用しているが、ディレクティブはアンダーバーではなく-を使用する。


.. inheritance-diagram:: matplotlib.patches matplotlib.lines matplotlib.text
    :parts: 2

docstringの取り込み

docstringがReSTで書かれていればそのまま取り込めるが、Google Style, Numpy styleで書かれている場合はsphinx.ext.napoleonを使用してpreprocessしなくてはならない。

.. automodule:: MyModule
- 再帰的に取り込みたい場合は:members:オプションを追加する
- :undoc-members:でdocstringのないメンバーも追加できる。
- :special-members:で__add__のような特殊なメンバーも追加

sphinx-apidoc

実際にプロジェクトのAPIドキュメントを作成する際は、sphinx-apidoc -F -o docs/ ${ソースコードのディレクトリ} でよい。

-F … makeファイルなどを同時に作成する。
-o … .rstファイルをアウトプットするディレクトリを指定。
-f … すでにファイルが出力先に存在する場合に上書きする。

実際に作成する際のベストプラクティスは

sphinx-apidoc -F -o docs/ apps/ でdocs以下を初期化
docs/conf.pyのextensionsにsphinx.ext.napoleonを追加してGoogle StyleとNumpy Styleのドキュメントを追加
sphinx-apidoc -f -o docs/ apps/で上書き