岩佐です.
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を押すと,
中身が表示されました.
見出しを勝手にインデックスしてくれたり, ソースコードを見やすくしてくれます. 書き方もシンプルです.