日本語 English
インターステラ株式会社の技術ブログです

【インターンステラ】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を押すと,

中身が表示されました.

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

PAGE TOP