python使用MkDocs自動生成文檔的操作方法

更新時間：2024年06月02日 11:58:55 作者：SkylerHu

python代碼注釋風格有很多,比較主流的有 reStructuredText風格、numpy風格、Google風格,自動生成文檔的工具也有很多,常見的有：Pydocs,Sphinx和MkDocs,本文給大家介紹了python使用MkDocs自動生成文檔的操作方法,需要的朋友可以參考下

前言

python代碼注釋風格有很多，比較主流的有 reStructuredText風格、numpy風格、Google風格。

自動生成文檔的工具也有很多，常見的有：

Pydocs python環(huán)境自帶，支持MarkDown，但功能比較簡單；
Sphinx 非常流行，默認支持reStructuredText風格注釋，若要支持MarkDown需要擴展插件支持；
MkDocs 優(yōu)勢是能夠很好的支持MarkDown格式來組織文檔，支持Google風格注釋;

對于熟悉MarkDown語法的人來說，推薦使用MkDocs，使用起來很方便。

使用MkDocs

環(huán)境

python3.9
安裝依賴

mkdocs==1.6.0
mkdocstrings==0.25.1
mkdocstrings-python==1.10.3
mkdocs-autorefs==1.0.1
mkdocs-material==9.5.24
mkdocs-same-dir==0.1.3

使用介紹

記得提前安裝相關依賴。

項目結構

截取部分展示：

├── pykit_tools  # 源碼目錄
│   ├── __init__.py
├── docs
│   ├── CHANGELOG-1.x.md
│   ├── CONTRIBUTING.md
│   └── Reference.md
├── .readthedocs.yaml
├── mkdocs.yml
├── README.md
├── requirements_docs.txt

配置文件

mkdocs.yml MkDocs主配置文件

site_name: pykit-tools
repo_url: https://github.com/SkylerHu/pykit-tools
docs_dir: .

# 配置主題
theme:
  name: readthedocs
  # name: material
  language: zh

# 配置文檔菜單
nav:
  - 首頁: README.md
  - 使用(Usage): docs/Reference.md
  - Release Notes: docs/CHANGELOG-1.x.md
  - 貢獻者指南: docs/CONTRIBUTING.md

# 插件配置
plugins:
  - search  # 內置插件，在標題中添加了一個搜索欄，允許用戶搜索您的文檔
  - same-dir  # 插件mkdocs-same-dir
  - autorefs
  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          # 配置解析代碼注釋的路徑
          paths: [pykit_tools]
          options:
            heading_level: 3  # 使用了三級菜單，在docs/Reference.md文檔中會有體現(xiàn)
            show_root_heading: true
            show_symbol_type_heading: true
            show_source: false
          selection:
            docstring_style: google

注釋生成文檔的配置

配置文件中 options 配置詳見 mkdocstrings globallocal-options

示例配置docs/Reference.md (截取部分) ，其中:::是特定格式，配置類或者函數(shù)的python模塊路徑：

# 使用(Usage)

## 裝飾器
::: decorators.common
    options:  # 會覆蓋全局配置
        members:
          - handle_exception
          - time_record

::: decorators.cache
    options:
        members:
            - method_deco_cache
            - singleton_refresh_regular

運行與構建

執(zhí)行 mkdocs serve 后可通過http://127.0.0.1:8000/訪問；

執(zhí)行 mkdocs build --clean 可以構建生成網(wǎng)站site目錄，可以將site添加到.gitignore文件中；

site目錄中的html、js等文件可用于自行部署成文檔服務網(wǎng)站。

部署

免費開源的部署，一般有兩個選擇：

Github Pages
- 發(fā)布到GitHub Pages的說明；
- 限制：每個用戶只能免費新建一個按照自己賬號名稱命名的pages；
readthedocs網(wǎng)站
- 支持 Sphinx 和 MkDocs 兩種方式的部署；
- 相關配置說明；
- 對開源項目文檔免費使用；
- 使用該種方式托管文檔，必須使用readthedocs的主題；

本文使用了readthedocs網(wǎng)站托管，網(wǎng)站可以使用Github賬號登錄，即可同步github項目信息，便捷導入生成文檔。

部署需要依賴配置文件.readthedocs.yaml, 內容示例如下：

version: 2

# 構建文檔需要的環(huán)境
build:
  os: ubuntu-22.04
  tools:
    python: "3.9"

# 文檔工具相關配置
mkdocs:
  configuration: mkdocs.yml

# 安裝依賴
python:
  install:
  - requirements: requirements_docs.txt  # 自己維護在項目中的依賴文件

具體導入步驟根據(jù)同步的GitHub項目列表，參考指引提示即可完成；

到此這篇關于python使用MkDocs自動生成文檔的操作方法的文章就介紹到這了,更多相關python MkDocs生成文檔內容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！

您可能感興趣的文章: