การกำหนดรูปแบบเอกสารด้วย reStructuredText

การสร้างเอกสารด้วย reStructuredText syntax ทำให้เอกสารที่พัฒนาง่ายในการอ่าน จัดรูปแบบได้ตามที่เห็น รูปแบบของ markup เป็น plaintext ซึ่งจะใช้ parser ในการแปลงให้อยู่ในรูปแบบเอกสารที่ต้องการเช่น html หรือ pdf เป็นต้น

การกำหนดรูปแบบ (Text Formatting)

1. Paragraphs

Paragraphs คือ block พื้นฐานของ reStructuredText ซึ่งแต่ละ paragraphs จะถูกแยกด้วย blank line 1 บรรทัด หรือมากกว่าหนึ่งก็ได้ ซึ่งย่อหน้ามีผลกับ reStructuredText ดังนั้นในการกำหนดบรรทัดใน paragraph เดียวกันจะต้องมี ย่อหน้าด้สนซ้ายเท่ากันในระดับเดียวกัน.

2. Inline markup และ special character

เราสามารถใช้ตัวอักษรพิเศษในการกำหนดรูปแบบข้อความมีอยู่ด้วยกันหลายตัว  ตัวอักษรพิเศษ * ถูกใช้ในการกำหนดรูปแบบตัวอักษรตัวหนา และ ตัวอักษรตัวเอียง ดังตัวอย่างด้านล่าง

• ตัวหนา **ภาษาไทย**  จะแสดงผลคือ  ภาษาไทย
• ตัวเอียง *ภาษาไทย*   จะแสดงผลคือ  ภาษาไทย

ตัวอักษรพิเศษ backquote  ``  จะใช้ในการกำหนดตัวอย่าง  code โดยการใช้งานดังนี้

``code sample``

แต่ถ้าต้องการใช้ * และ `  ในเอกสารด้วยซึ่งจะทำให้สับสนกับ inline markup ได้ ดังนั้นจึงใช้  backslash นำหน้าสำหรับ * และ ` ที่จะใช้แสดงผลของเอกสาร

3. Lists and Quote-like blocks

การกำหนด list สามารถทำได้โดยการใช้ * นำหน้า

* bulleted list
* bulleted list
* bulleted list

สำหรับ numbered list ก็ให้ใช้ตัวเลขนำหน้า

1. numbered list
2. numbered list

ถ้าต้องการ list ที่กำหนดเลขโดยอัตโนมัติให้ใช้ # นำหน้า

#. numbered list
#. numbered list

การกำหนด list ซ้อนกันหลายๆชั้นสามารถทำได้ แต่ต้องแยกแต่ละ list ออกด้วย blank line

*. bulleted list
*. bulleted list
    *. bulleted list
    *. bulleted list
*. bulleted list

4. Source code

การกำหนด code block ทำได้โดยใช้ special marker :: ที่ตอนจบของ paragraph และจะต้องแยกจากส่วนอื่นด้วย blank line เช่นเดียวกับ paragraph ทั่วไป

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

            public class reStructuredTest {
                    public reStructuredTest(){
                    }
            }

5. Table

การสร้างตารางทำได้ในสองรูปแบบคือแบบ grid table และ simple table โดยการสร้างตารางแบบ grid table ทำได้ด้วยการวาดตารางด้วยตัวเอง

+------------------------+------------+----------+----------+
| 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             | ...        | ...      |          |
+------------------------+------------+----------+----------+

สำหรับ Simple tables จะเขียนง่ายกว่ารูปแบบแรก แต่มีข้อมจำกัดคือ จะต้องมีมากกว่า 1 row และ column แรกไม่อนุญาติให้มีหลายบรรทัด

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

6. Hyperlinks

การกำหนด hyperlink ทำได้โดยการกำหนดรูปแบบดังนี้

`Link text <http://example.com/>`_

section header กำหนดโดยใช้การทำ underlining โดยที่ความยาวของ underlining จะต้องเท่ากับจำนวนตัวอักษรของ header

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

การกำหนดระดับของ header จะทำได้โดย

• # ร่วมกับ overline  สำหรับกำหนด  part header
• * ร่วมกับ overline สำหรับกำหนด chapter header
• = สำหรับกำหนด section header
• - สำหรับกำหนด subsection header
• ^ สำหรับกำหนด subsubsection header
• ” สำหรับกำหนด paragraph header

 

อ้างอิง

1. http://www.sphinx-doc.org/en/1.5.1/rest.html
2. http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html