2023年3月2日
岩佐です.
Sphinxでドキュメントを作成する際, reStructuredTextという簡易マークアップ言語を使って記述します. そこで, よく使いそうな簡単な構文を書いておきます.
以前Sphinxの始め方で作ったsample projectを使います. が, 新しく始めてもいいでしょう.
その場合は,
$ sphinx-quickstart
Project nameとAuthor nameを適当に決め, autodocをyにしておく以外はそのままEnterを押しましょう.
ディレクトリの中身はこのような感じですよね.
$ ls Makefile _build _static _templates conf.py index.rst make.bat
ここで新しいrstファイルを作ります.
$ vim sample.rst
とにかく書いてみましょう.
Section ======= =========== Subsection1 =========== reStructuredText sample *italic* **bold** ``code sample`` * table ===== ===== ====== input output ------------ ------ A B A or B ===== ===== ====== False False False True False True False True True True True True ===== ===== ====== * link `Sphinx `_. =========== Subsection2 =========== 1. code-block .. code-block:: python from django.http import HttpResponse def hello(request); return HttpResponse("Hello World") .. 2. object's document .. py:function:: enumerate(sequence[, start=0]) Return an iterator that yields tuples of an index and an item of the *sequence*. (And so on.)
index.rstも以下のように編集します. “sample”は上で作ったファイル名です.
.. sample documentation master file, created by sphinx-quickstart on Sat Jul 14 11:18:11 2018. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. sample documentation ==================== .. toctree:: :maxdepth: 2 :caption: Contents: sample Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`
そしてビルド して_build/html/index.htmlを開く.
$ make html $ open _build/html/index.html
すると以下のようなページが表示されます.
Subection1を押すと,
中身が表示されました.
見出しを勝手にインデックスしてくれたり, ソースコードを見やすくしてくれます. 書き方もシンプルです.