【インターンステラ】reStructuredTextの書き方

岩佐です.

Sphinxでドキュメントを作成する際, reStructuredTextという簡易マークアップ言語を使って記述します. そこで, よく使いそうな簡単な構文を書いておきます.

以前Sphinxの始め方で作ったsample projectを使います. が, 新しく始めてもいいでしょう.

その場合は,
$ sphinx-quickstart
Project nameとAuthor nameを適当に決め, autodocをyにしておく以外はそのままEnterを押しましょう.

reStructuredTextの構文

ディレクトリの中身はこのような感じですよね.
$ 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を押すと,
中身が表示されました.

見出しを勝手にインデックスしてくれたり, ソースコードを見やすくしてくれます. 書き方もシンプルです.

このブログの人気の投稿

【AWS】IAMFullAccessを付与せずIAM Roleの作成とアタッチを行う方法

【AWS】EBSボリューム自動取得/削除 を Lambda で実行 (世代管理も)

【GCP】Compute EngineでVPNサーバーを立てるときの注意点