reStructuredText

reStructuredText (reST) adalah bahasa markup teks biasa default yang digunakan oleh Sphinx.

Paragraf

Paragraf (ref) adalah blok paling dasar dalam dokumen reStructuredText. Paragraf hanyalah potongan teks yang dipisahkan oleh satu atau beberapa baris kosong. Seperti dalam Python, indentasi penting dalam reStructuredText, jadi semua baris dalam paragraf yang sama harus diratakan ke kiri dengan tingkat indentasi yang sama.

Inline markup

• satu tanda bintang: *text* untuk penekanan (huruf miring)

• dua tanda bintang: **text** untuk penekanan kuat (huruf tebal), dan

• tanda kutip terbalik (backquotes) ``text`` untuk contoh kode

List dan blok Quote

Beri tanda bintang di awal paragraf dan buat indentasi dengan benar. Hal yang sama berlaku untuk daftar bernomor; daftar tersebut juga dapat diberi nomor otomatis menggunakan tanda #:

* Ini adalah daftar berpoin.
* Daftar ini memiliki dua item, item kedua menggunakan dua baris.

1. Ini adalah daftar bernomor.
2. Daftar ini juga memiliki dua item.

#. Ini adalah daftar bernomor.
#. Daftar ini juga memiliki dua item.

Daftar bertingkat dimungkinkan, namun perlu diperhatikan bahwa daftar tersebut harus dipisahkan dari item daftar induk dengan baris kosong:

* this is
* a list

  * with a nested list
  * and some subitems

* and here the parent list continues

Daftar definisi dibuat sebagai berikut:

term (up to a line of text)
   Definition of the term, which must be indented

   and can even consist of multiple paragraphs

next term
   Description.

Blok baris adalah cara untuk mempertahankan jeda baris:

| These lines are
| broken exactly like in
| the source file.

Ada juga beberapa blok khusus yang tersedia:

• daftar bidang (ref, dengan peringatan yang dicatat dalam Field Lists)

• daftar opsi (ref)

• blok literal yang dikutip (ref)

• blok doctest (ref)

Literal blocks

Blok kode literal (ref) diperkenalkan dengan mengakhiri paragraf dengan penanda khusus ::. Blok literal harus diberi indentasi (dan, seperti semua paragraf, dipisahkan dari blok di sekitarnya dengan baris kosong):

This is a normal text paragraph. The next paragraph is a code sample::

   It is not processed in any way, except
   that the indentation is removed.

   It can span multiple lines.

This is a normal text paragraph again.

Penanganan penanda :: sangat cerdas:

• Jika muncul sebagai paragraf tersendiri, paragraf tersebut sepenuhnya dihilangkan dari dokumen.

• Jika didahului oleh spasi, penanda tersebut dihapus.

• Jika didahului oleh selain spasi, penanda tersebut diganti dengan satu titik dua.

Doctest blocks

Blok doctest (ref) adalah sesi Python interaktif yang dipotong dan ditempel ke dalam docstring. Blok ini tidak memerlukan sintaks blok literal. Blok doctest harus diakhiri dengan baris kosong dan tidak boleh diakhiri dengan perintah yang tidak digunakan:

>>> 1 + 1
2

Tables

Untuk tabel grid (ref), Anda harus "mengecat" sendiri grid selnya. Tampilannya seperti ini:

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | ...        | ...      |          |
+------------------------+------------+----------+----------+

Header row, column 1 (header rows optional)	Header 2	Header 3	Header 4
body row 1, column 1	column 2	column 3	column 4
body row 2	...	...

Tabel sederhana (ref) lebih mudah ditulis, tetapi terbatas: tabel harus berisi lebih dari satu baris, dan sel kolom pertama tidak boleh berisi beberapa baris. Tabel tersebut tampak seperti ini:

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

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

Sections

Judul bagian dibuat dengan menggarisbawahi (dan jika perlu menggarisatasi) judul bagian dengan karakter tanda baca, setidaknya sepanjang teks:

=================
This is a heading
=================

Biasanya, tidak ada level heading yang ditetapkan untuk karakter tertentu karena strukturnya ditentukan dari rangkaian heading. Namun, konvensi ini digunakan dalam Panduan Pengembang Python untuk mendokumentasikannya yang dapat Anda ikuti:

# with overline, for parts

* with overline, for chapters

= for sections

- for subsections

^ for subsubsections

" for paragraphs

Tentu saja, Anda bebas menggunakan karakter penanda Anda sendiri (lihat dokumentasi reStructuredText), dan menggunakan tingkat penyisipan yang lebih dalam, tetapi perlu diingat bahwa sebagian besar format target (HTML, LaTeX) memiliki kedalaman penyisipan yang terbatas.

Field Lists

Daftar bidang (field lists) adalah urutan bidang yang ditandai seperti ini:

:fieldname: Field content

fieldname:

Field content

Umumnya digunakan dalam dokumentasi Python:

def my_function(my_arg, my_other_arg):
    """A function just for me.

    :param my_arg: The first of my arguments.
    :param my_other_arg: The second of my arguments.

    :returns: A message (just for me, of course).
    """

def my_function(my_arg, my_other_arg):

"""A function just for me.

param my_arg:

The first of my arguments.

param my_other_arg:

The second of my arguments.

returns:

A message (just for me, of course).

"""