Cách tạo project documentation cho codebase Python dùng Sphinx
TIL
763
Python
70
sphinx
1
White

Minh-Trung Nguyễn viết ngày 21/12/2018

TIL Day47

Đặt đầu bài:

  • Câu hỏi: Có cách nào để tạo ra những tài liệu mô tả dự án và mô tả codebase Python (về function, method, class) trông chuyên nghiệp như các trang web documentation của Python (link cho Python), hay Numpy (link cho Numpy)?
  • Trả lời: Một trong những cách để tạo project documentation kiểu trên là sử dụng sphinx (link), bao gồm việc comment codebase theo 1 format nhất định, rồi dùng sphinx để build documentation dựa trên các comment đó. Tất nhiên là có thể có những cách khác nhưng chưa tìm hiểu hết.

Cách tạo documentation cho codebase Python dùng Sphinx

Bước 1: Cài sphinx theo hướng dẫn ở đây

Bước 2: Trong folder dự án project_A (với sub-folder source code src), tạo 1 folder tên là docs (có thể tạo tên khác).

|
|--project_A
        |
        |---docs
        |
        |---src
                |
                |---utils.py, main.py, function_1.py

Bước 3: cd vào folder docs, chạy lệnh sphinx-quickstart

Trong các bước mà sphinx-quickstart hỏi, nhớ chọn:

  • Separate source and build directories (y/n) [n]: y --> giúp tạo ra 2 folder buildsource bên trong folder docs.
  • autodoc: automatically insert docstrings from modules (y/n): y
  • coverage: checks for documentation coverage (y/n) [n]: y

Sau bước này, trong folder structure sẽ trông gần như sau:

alt text

Bước 4: Thay đổi file config.py bên trong folder docs

File config.py là nơi sphinx refer đến để generate ra documentation. Ta cần:

Chỉ cho sphinx biết vị trí folder chứa codebase Python.

Ví dụ codebase python đang đặt trong folder src bên trong folder project_A, đường dẫn trong Windows là D:\Project_A\src, thì sửa đoạn sau trong file config.py thành:

# import os
# import sys
# sys.path.insert(0, 'D:\Project_A\src')
Thêm “Napoleon” vào danh sách các extension của sphinx. Sửa đoạn sau trong file config.py thành:
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.coverage', 'sphinx.ext.napoleon']

Trong các exentsion nói trên:

  • autodoc là để đọc các docstring (chính là các comment theo format chuẩn ở từng function, method, class trong các module .py)
  • napoleon là để convert các docstring từ format của Goolge/ Numpy thành format mà sphinx dùng (mặc định là reStructuredText)

Bước 5: Viết các docstring bên trong các module .py

Nếu muốn sphinx generate document từ các comment bên trong module, thì chắc chắn phải tự mình viết các comment này. Xem mẫu ở đây:

  • Theo style của Numpy: link
  • Theo style của Google: link

Đại loại theo style của Numpy nó sẽ kiểu sau:

def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
    """Example function with PEP 484 type annotations.

    The return type must be duplicated in the docstring to comply
    with the NumPy docstring style.

    Parameters
    ----------
    param1
        The first parameter.
    param2
        The second parameter.

    Returns
    -------
    bool
        True if successful, False otherwise.

    """

Bước 6: Chạy lệnh sphinx-apidoc để generate ra các file .rst ứng với các module .py

Chạy lệnh sau từ trong folder project_A:

sphinx-apidoc -o <output dir> <code dir>

trong đó <ouput dir> để là docs, còn <code dir> để là src.

Kết quả là bên trong folder docs sẽ xuất hiện các file sau:

  • index.rst: để build file index.html sau này
  • main.rst, utils.rst, function_1.rst: để build các file main.html, utils.html, và function_1.html sau này

Đuổi .rst là ứng với định dạng reStructuredText (tương tự đuôi .md ứng với Markdown). Người dùng hoàn toàn có thể cusotmize các file .rst dựa trên các cú pháp của reStructuredText, ví dụ xem ở đây.

Xem thêm về sphinx-apidocđây

Bước 7: Chạy lệnh sphinx-build để generate ra documentation với định dạng html/pdf/...

Từ command line, bên trong folder project_A, gọi lệnh sau:

sphinx-build -b <sourcedir> <outputdir>

với <sourcedir>docs/source, và <outputdir>docs/build

  • sphinx-build sẽ tạo ra documentation từ các files trong <sourcedir>, rồi đặt documentation bên trong <outputdir>.
  • sphinx-build sẽ xem tìm kiếm file conf.py bên trong <sourcedir> để đọc các thông số cấu hình
  • sphinx-build có thể tạo ra documentation ở nhiều định dạng, mặc định là HTML.

Xem thêm về sphinx-buildđây

Bước 8: Xem thành quả trong folder docs\build

Vào folder docs\build, chạy index.html để xem thành quả.

Ghi chú:

Còn rất nhiều tính năng của sphix chưa khai thác hết mà cũng không có thời gian để vần. Các bước làm của sphinx tương đối phức tạp.

alt text

Tham khảo

https://romanvm.pythonanywhere.com/post/autodocumenting-your-python-code-sphinx-part-ii-6/

https://samnicholls.net/2016/06/15/how-to-sphinx-readthedocs/

https://medium.com/@eikonomega/getting-started-with-sphinx-autodoc-part-1-2cebbbca5365

https://codeandchaos.wordpress.com/2012/07/30/sphinx-autodoc-tutorial-for-dummies/

http://daouzli.com/blog/pyment.html

ngminhtrung 20-12-2018

Bình luận


White
{{ comment.user.name }}
Bỏ hay Hay
{{comment.like_count}}
Male avatar
{{ comment_error }}
Hủy
   

Hiển thị thử

Chỉnh sửa

White

Minh-Trung Nguyễn

63 bài viết.
121 người follow
Kipalog
{{userFollowed ? 'Following' : 'Follow'}}
Cùng một tác giả
White
53 16
Đăng lại một bài đã viết từ cách đây mấy tháng. Chủ đề này đã có không ít, nhưng chẳng hiểu sao lượng bài tự viết của dân lập trình người Việt ta v...
Minh-Trung Nguyễn viết hơn 2 năm trước
53 16
White
28 6
Ghi chú: Tiêu đề hoàn toàn mang tính câu view. Bài copy từ blog của tác giả :) Tại sao lại có bài viết này? Một ngày đẹp giời tôi cần kiểm t...
Minh-Trung Nguyễn viết gần 3 năm trước
28 6
White
17 4
Về bước tìm và xử lý dữ liệu của Việt Nam phục vụ Data Visualization nền web Làm việc với D3js được nửa năm, một trong những điều bận lòng là chưa...
Minh-Trung Nguyễn viết hơn 2 năm trước
17 4
Bài viết liên quan
White
0 4
fCC: Technical Documentation Page note So I have finished the HTML part of this exercise and I want to come here to lament about the lengthy HTML ...
HungHayHo viết hơn 2 năm trước
0 4
{{like_count}}

kipalog

{{ comment_count }}

bình luận

{{liked ? "Đã kipalog" : "Kipalog"}}


White
{{userFollowed ? 'Following' : 'Follow'}}
63 bài viết.
121 người follow

 Đầu mục bài viết

Vẫn còn nữa! x

Kipalog vẫn còn rất nhiều bài viết hay và chủ đề thú vị chờ bạn khám phá!