7 มิถุนายน 2558

Published 6/07/2558 by with 0 comment

สร้างเอกสารโปรเจคด้วย mkdocs

สวัสดีผู้อ่านทุกท่านครับ เมื่อผมหรือคุณพัฒนาโปรแกรม ไลบรารี ขึ้นมา จะต้องมีเอกสารประกอบใช้งานควบคู่ไปด้วย เพื่อให้สามารถใช้งานโปรแกรม ไลบรารี ที่พัฒนาขึ้นมาได้ง่ายขึ้น บทความนี้ผมจะพาผูอ่านไปแนะนำการสร้างเอกสารโปรเจคด้วย mkdocs

mkdocs เป็นโมดูลสำหรับใช้สร้างเอกสารโปรเจคโดยใช้ Markdown ในการจัดรูปแบบเอกสาร โดยจะแสดงออกมาเป็นหน้าเว็บ ใช้ License: BSD รองรับทั้ง Python 2 , Python 3 ครับ

สามารถติดตั้งได้โดยใช้คำสั่ง pip:
$ pip install mkdocs

เริ่มต้นการใช้งาน mkdocs


เปิดคอมมาไลน์ขึ้นมา ใช้คำสั่ง
$ mkdocs new my-project
$ cd my-project

คำอธิบายคำสั่ง
mkdocs new my-project เป็นคำสั่งสร้างโปรเจคเอกสาร my-project ขึ้นมา
cd my-project เข้าไปยังโฟลเลอร์ my-project

เมื่อเข้าไปยังโฟลเลอร์ จะพบกับไฟล์ mkdocs.yml เป็นไฟล์ที่กำหนดการตั้งค่าของเอกสาร และจะมีโฟลเลอร์ย่อยอยู่ที่ชื่อว่า docs ภายในจะเก็บเอกสาร Markdown ไว้ครับ

ลองรัน mkdocs
$ mkdocs serve
Running at: http://127.0.0.1:8000/

เข้าไปที่ http://127.0.0.1:8000/ จะพบกับ



สามารถตั้งค่าชื่อเอกสารได้จากไฟล์ mkdocs.yml ครับ
site_name: เอกสาร

ในไฟล์ mkdocs.yml

สร้างเอกสารเพิ่มและตั้งค่าธีมของ mkdocs


เมื่อสร้างเอกสาร Markdown เพิ่มขึ้นมาต้องการเพิ่มเอกสารเข้าไปยัง mkdocs ให้บันทึกเอกสาร Markdown เข้าไปยังโฟลเลอร์ docs ในโฟลเลอร์ของเอกสารโปรเจคครับ
ตัวอย่างเช่น ผมเพิ่มหน้า index.md กับ about.md เข้าไปยังโฟลเลอร์ docs เสร็จแล้วเข้าไปแก้ไขไฟล์ mkdocs.yml โดยสามารถเพิ่มหน้าเอกสารได้ดังนี้
pages:
- Home: index.md
- About: about.md

สามารถเปลี่ยนธีมของ mkdocs ได้โดยเพิ่มคำสั่ง
theme: ชื่อธีม

เข้าไป ผมใช้ธีมของ readthedocs
theme: readthedocs

เมื่อลองรัน
$ mkdocs serve
Running at: http://127.0.0.1:8000/

ผลลัพธ์

สร้างเอกสารโปรเจคด้วย mkdocs

สร้างเอกสาร HTML


ใช้คำสั่ง
$ mkdocs build

จะได้โฟลเลอร์ site ขึ้นมา โดยจะเก็บไฟล์ HTML ที่ส่งออกมาจาก mkdocs ครับ

อ่านเอกสารเพิ่มเติมได้ที่ http://www.mkdocs.org
ติดตามบทความต่อไปนะครับ
ขอบคุณครับ

0 ความคิดเห็น:

แสดงความคิดเห็น

แสดงความคิดเห็นได้ครับ :)