Easy and beautiful documentation with Sphinx

Easy and beautiful documentation with Sphinx

link : http://www.ibm.com/developerworks/library/os-sphinx-documentation/index.html

 

Install sphinx and sphinx-quickstart

link : https://bitbucket.org/5311565070/w4_1/commits/d21c95b93b9521571202f9c79d3ddbc2e72d5496

     เป็นการติดตั้ง sphinx โดยใช้คำสั่ง $ easy_install sphinx

     ต่อมาเป็นการสร้าง documentation project แบบ quick start โดยใช้คำสั่ง $ sphinx-quickstart เมื่อพิมพ์คำสั่งนี้แล้ว มันก็จะรัน โดยให้เรากด enter ไปเรื่อยๆ จนเสร็จ เมื่อการสร้าง documentation project เสร็จแล้วจะมีไฟล์ที่ปรากฎ ดังนี้

     - Makefile

     - _build

     - _static

     - conf.py

     - index.rst 

ซึ่งแต่ละไฟล์ดังกล่าว จะมีหน้าที่ดังนี้ 
- Makefile เป็นเหมือนไฟล์ที่รวบรวม library ต่างๆ ไว้สำหรับนำไปใช้ได้ 
- _build  เป็น folder ที่ไว้สำหรับแสดง output 
- _static เป็น folder ที่ไว้ใช้เก็บพวกข้อมูลต่างๆ เช่น พวกรูปภาพ 
- conf.py เป็นไฟล์ที่กำหนดค่าของ sphinx ( ไฟล์นี้จะมีเมื่อมีการสร้าง new documentation project ขึ้น) 
- index.rst  เป็นไฟล์ที่ใช้สำหรับเชื่อมต่อกับไฟล์อื่นๆ 

Getting started

link : https://bitbucket.org/5311565070/w4_1/commits/f9d4883030cd3eac8675a0935b8a6c4a7f7aad16

     เป็นการเริ่มต้นการทดสอบ เริ่มแรกให้เข้าไปแก้ไขในไฟล์ index.rst โดยการเพิ่มคำว่า example (ในการย่อหน้า ให้กด spaces 3 ครั้ง) ลงในตำแหน่งตามด่านล่างนี้

Contents:

 .. toctree:: 

    :maxdepth: 2 

   example

หลังจากนั้นให้สร้างไฟล์ example.rst โดยใส่ข้อมูลดังนี้ (เฉพาะข้อความที่เป็นสีส้ม)

This is a Title 

=============== 

That has a paragraph about a main subject and is set when the '=' 

is at least the same length of the title itself. 

Subject Subtitle

----------------

Subtitles are set with '-' and are required to have the same length 

of the subtitle itself, just like titles. 

Lists can be unnumbered like: 

 * Item Foo 

  * Item Bar 

Or automatically numbered: 

 #. Item 1 

 #. Item 2 

Inline Markup 

-------------

Words can have *emphasis in italics* or be **bold** and you can define 

code samples with back quotes, like when you talk about a command: ``sudo`` 

 gives you super user powers! 

     ต่อมาเป็นการสร้างไฟล์ html โดยใช้คำสั่ง $ make html เมื่อสร้างเสร็จจะมี folder 2 folder ขึ้นมา
     - doctrees
     - html

     หลังจากนั้นให้เราเข้าไปคลิกที่ไฟล์ index.html ( doc/_build/html/index.html ) เพื่อเข้าไปดูรูปแบบ html ที่เรา make ขึ้น จะมีลักษณะดังนี้

Graphic

link : https://bitbucket.org/5311565070/w4_1/commits/292cb1ce33d31ed9bc4edb9fb25750ee20698a69

     เป็นการใช้กราฟฟิก ในที่นี้จะเป็นการใส่รูปภาพ 
     โดยใช้คำสั่ง ..image:: ตำแหน่งของรูปภาพ เช่น ..image:: _static/system_activity.jpg
     เราต้องนำรูปที่เราจะใช้มาไว้ที่ doc/_build/html/_static ก่อน