สร้างเอกสารด้วย MkDocs
ผลงานนี้ ใช้ สัญญาอนุญาตของครีเอทีฟคอมมอนส์
เขียนโดย นาย วรรณพงษ์ ภัททิยไพบูลย์
เอกสารเป็นสิ่งจำเป็นอย่างยิ่งต่อการพัฒนาโปรแกรม นอกจากนั้นมีความจำเป็นต่อการอธิบายความรู้ที่มีในทุกสาขาวิชา เพื่อให้ผู้อื่นสามารถเข้าถึงความรู้ได้ง่ายขึ้นผ่านตัวอักษร
เนื้อหาในเอกสารนี้จะกล่าวถึงการสร้างเอกสารด้วย MkDocs ซึ่งใช้ Markdown ในการเขียนเอกสาร ผู้อ่านควรมีความรู้ในการเขียนเอกสาร Markdown
สารบัญ
บทที่ 1 ติดตั้ง MkDocs
MkDocs เป็นโมดูลในภาษาไพทอน (Python) สำหรับใช้สร้างเอกสาร Markdown
การติดตั้ง
เปิด cmd ใช้คำสั่งpip install mkdocsบทที่ 2 สร้างเอกสาร
เปิด cmd ขึ้นมา แล้วใช้คำสั่ง
mkdocs new ชื่อเอกสารได้ระบบไฟล์ดังนี้
แล้วเข้าไปยังโฟลเดอร์เอกสารที่ถูกสร้างขึ้นมา
ทำการสร้างเอกสารในรูปแบบไฟล์ .md ตามที่ต้องการ โดยไฟล์ต้องถูกเก็บไว้ในโฟลเดอร์ docs
แล้วทำการเปิดไฟล์ mkdocs.yml ขึ้นมา โดยมีโค้ดดังนี้
site_name: ชื่อเอกสารกำหนดชื่อเอกสาร
กำหนดได้โดยเปลี่ยน site_name โดยต้องเป็นภาษาอังกฤษเท่านั้น
กำหนดธีมเอกสาร
กำหนดได้โดยเพิ่มธีมที่ต้องการที่ theme ในที่นี้เลือก readthedocs
theme: readthedocsหากต้องการสร้างธีมเอกสารด้วยตนเอง อ่านเอกสารได้ที่ http://www.mkdocs.org/user-guide/custom-themes/
กำหนดเนื้อหาของเอกสาร
ค่าเริ่มต้นของไฟล์ mkdocs.yml มีการดึงข้อมูลจากไฟล์ index.md ในโฟลเดอร์ docs หากมีไฟล์ .md มากกว่า 1 ไฟล์ขึ้นไป สามารถกำหนดได้ดังนี้
สมมุติมีไฟล์ index.md เป็นไฟล์บทนำ และไฟล์ document.md เป็นไฟล์เนื้อหา สามารถกำหนดค่าเนื้อหาเอกสารได้โดยเพิ่ม pages
pages:
- Home: index.md- Document: document.mdสรุป
pages:
- ชื่อ: ไฟล์เอกสาร.mdโดยมีข้อแม้ คือ ชื่อกับไฟล์เอกสาร ต้องเป็นภาษาอังกฤษ เนื่องจาก MkDocs ไม่รองรับภาษาไทย แต่เนื้อหาภายในไฟล์ .md สามารถเป็นภาษาไทยได้
ได้ไฟล์ mkdocs.yml ดังนี้
site_name: ชื่อเอกสาร
theme: ธีม
pages:
- ชื่อ: ไฟล์เอกสาร.mdอ่านเอกสารอย่างละเอียดได้ที่ http://www.mkdocs.org/
0 ความคิดเห็น:
แสดงความคิดเห็น
แสดงความคิดเห็นได้ครับ :)