Hi các bạn,
Trong công việc, việc document lại code, document lại các libraries trong dự án, business logics,… là điều dường như tất yếu phải không. Có thể chúng ta có rất nhiều cách để thỏa mãn vụ này như viết Word, Google Docs, GitLab wiki,…
Tuy nhiên những cách thông thường như vậy, ta quản lý document của ta rất khó, rất nhiều và lung tung. Và đôi khi, ta cần search 1 chi tiết nào đó, ta sẽ ko search dc mà phải chui vào từng files, từng trang,… Một cực hình phải ko.
Và từ đó, ta sẽ tìm ra 1 hướng khác, làm ra 1 site để chứa document và hỗ trợ ta tìm kiếm document cần thiết, nhưng mà nếu code thì khá tốn thời gian, cũng như các libraries free ngoài kia, họ ko hề code 1 site document mà họ dùng một phần mềm nhất định để hỗ trợ họ viết và dựng ra site document theo ý họ muốn.
Mình đã sử dụng và hôm nay sẽ giới thiệu với bạn luôn phần mềm có tên là: MkDocs.
1/ Giới thiệu về MkDocs
MkDocs là một phần mềm cực nhanh, dễ sử dụng hỗ trợ bạn generate ra site document theo ý của bạn.
Các dạng files document MkDocs hỗ trợ:
- Markdown (phổ biến nhất)
- Text (txt)
- Html
MkDocs sẽ dựng ra các trang html và bạn có thể host site document mọi nơi (Apache, Nginx, IIS,…) và ngay cả GitHub pages.
Trang chủ: https://www.mkdocs.org/
2/ Yêu cầu tối thiểu
Đã cài Python (https://www.python.org/downloads/)
Các version Python mà MkDocs hỗ trợ: 2.7, 3.4, 3.5, 3.6, 3.7
Lưu ý đối với các bạn xài WINDOWS, khi cài xong nhớ tick dòng này trước khi tắt nhé:
Sau khi cài xong, bạn có thể bật Command Line (cmd) lên để check python và pip với lệnh như sau:
$ python --version
Python 2.7.2
$ pip --version
pip 1.5.2
3/ Cài đặt MkDocs
Chỉ đơn giản là chạy lệnh này 😀
pip install mkdocs
Sau khi cài xong, bạn có thể kiểm tra version như sau:
$ mkdocs --version
mkdocs, version 0.15.3
4/ Tạo ra project document đầu tiên
Thông qua 1 dòng lệnh này, bạn sẽ tạo ra được một project document:
Project sẽ có cấu trúc như sau:
Trong đó:
- mkdocs.yml là file config chính về trang document của bạn (config title, sidebar,…)
- docs là thư mục bạn sẽ chứa toàn bộ document trong đó.
5/ Dựng dev-server để test trang document
Với lệnh:
mkdocs serve
Bạn sẽ dựng ra được 1 dev-server và bạn có thể vào url mà MkDocs cung cấp để test document của mình 😀
$ mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000
[I 160402 15:50:43 handlers:58] Start watching changes
[I 160402 15:50:43 handlers:60] Start detecting changes
Ngoài ra, nếu bạn muốn dev-server chạy và xem dc trong toàn bộ mạng LAN local, các bạn có thể xài lệnh này:
mkdocs serve -a 0.0.0.0:8080
Như thế thì site dev này với những người trong mạng LAN sẽ truy cập và xem được.
Site khi ta chạy dev và vào thử khi vừa mới tạo project:
6/ Build ra trang document
Chạy lệnh sau để build ra trang document:
mkdocs build
Sau khi build xong, các bạn sẽ thấy thư mục có tên site trong root project folder của bạn. Bạn có thể copy thư mục đó và deploy lên server mà bạn muốn, rất là light-weight phải ko nhỉ? 😀
7/ Cách viết document, cấu hình trang document, themes,…
Cách viết document: sử dụng markdown syntax là chính, bạn có thể mix giữa html và markdown nếu muốn, Mkdocs vẫn hiểu 😀
Thông tin thêm: https://www.mkdocs.org/user-guide/writing-your-docs/
Về cách cấu hình trang document (tiêu đề, theme, sidebar,…), các bạn có thể tham khảo tại: https://www.mkdocs.org/user-guide/configuration/
8/ Kết luận
Với MkDocs, các bạn có thể dựng ra trang document theo ý muốn, nhỏ gọn, dựng nó theo ý bạn và hỗ trợ người sử dụng trang document bạn tiếp cận nhanh, gọn dễ hơn cũng như là khả năng tìm kiếm document.
Lưu ý là ta nên sử dụng Markdown nhé, để nó có thể dựng ra Table of Contents cho page của bạn được cũng như phát huy khả năng tìm kiếm của tốt nhất nó 😀
Cám ơn các bạn đã quan tâm theo dõi!
From Seth Phat (Documentation Specialist) with love!