การสร้างเอกสารด้วย 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/>`_
ในกรณีที่ link text เป็น web address อยู่แล้ว ไม่จำเป็นต้องกำหนด markup พิเศษใดๆ parser จะตีความว่าเป็น link ให้เองเช่นเดียวกับ mail address
7.Section Header
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