5 มกราคม 2560

Published มกราคม 05, 2560 by with 0 comment

สร้างเอกสารด้วย MkDocs

สร้างเอกสารด้วย MkDocs


license
ผลงานนี้ ใช้ สัญญาอนุญาตของครีเอทีฟคอมมอนส์

เขียนโดย นาย วรรณพงษ์ ภัททิยไพบูลย์

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


เนื้อหาในเอกสารนี้จะกล่าวถึงการสร้างเอกสารด้วย 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 ความคิดเห็น:

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

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