python使用MkDocs自动生成文档的操作方法

画梁落香

前言

python代码注释风格有很多，比较主流的有 reStructuredText风格、numpy风格、Google风格。
自动生成文档的工具也有很多，常见的有：

• Pydocs python环境自带，支持MarkDown，但功能比较简单；
  
• Sphinx 非常流行，默认支持reStructuredText风格注释，若要支持MarkDown需要扩展插件支持；
  
• MkDocs 优势是能够很好的支持MarkDown格式来组织文档，支持Google风格注释;
  

对于熟悉MarkDown语法的人来说，推荐使用MkDocs，使用起来很方便。

使用MkDocs


环境

• python3.9
  
• 安装依赖
  

1. mkdocs==1.6.0
   
2. mkdocstrings==0.25.1
   
3. mkdocstrings-python==1.10.3
   
4. mkdocs-autorefs==1.0.1
   
5. mkdocs-material==9.5.24
   
6. mkdocs-same-dir==0.1.3

复制代码

使用介绍

记得提前安装相关依赖。

项目结构

截取部分展示：

1. ├── pykit_tools  # 源码目录
   
2. │   ├── __init__.py
   
3. ├── docs
   
4. │   ├── CHANGELOG-1.x.md
   
5. │   ├── CONTRIBUTING.md
   
6. │   └── Reference.md
   
7. ├── .readthedocs.yaml
   
8. ├── mkdocs.yml
   
9. ├── README.md
   
10. ├── requirements_docs.txt

复制代码

配置文件

1. mkdocs.yml

复制代码

MkDocs主配置文件

1. site_name: pykit-tools
   
2. repo_url: https://github.com/SkylerHu/pykit-tools
   
3. docs_dir: .
   
4. 
   
5. # 配置主题
   
6. theme:
   
7.   name: readthedocs
   
8.   # name: material
   
9.   language: zh
   
10. 
    
11. # 配置文档菜单
    
12. nav:
    
13.   - 首页: README.md
    
14.   - 使用(Usage): docs/Reference.md
    
15.   - Release Notes: docs/CHANGELOG-1.x.md
    
16.   - 贡献者指南: docs/CONTRIBUTING.md
    
17. 
    
18. # 插件配置
    
19. plugins:
    
20.   - search  # 内置插件，在标题中添加了一个搜索栏，允许用户搜索您的文档
    
21.   - same-dir  # 插件mkdocs-same-dir
    
22.   - autorefs
    
23.   - mkdocstrings:
    
24.       default_handler: python
    
25.       handlers:
    
26.         python:
    
27.           # 配置解析代码注释的路径
    
28.           paths: [pykit_tools]
    
29.           options:
    
30.             heading_level: 3  # 使用了三级菜单，在docs/Reference.md文档中会有体现
    
31.             show_root_heading: true
    
32.             show_symbol_type_heading: true
    
33.             show_source: false
    
34.           selection:
    
35.             docstring_style: google

复制代码

注释生成文档的配置

配置文件中

1. options

复制代码

配置详见 mkdocstrings globallocal-options
示例配置

1. docs/Reference.md

复制代码

(截取部分) ， 其中

1. :::

复制代码

是特定格式，配置类或者函数的python模块路径：

1. # 使用(Usage)
   
2. 
   
3. ## 装饰器
   
4. ::: decorators.common
   
5.     options:  # 会覆盖全局配置
   
6.         members:
   
7.           - handle_exception
   
8.           - time_record
   
9. 
   
10. ::: decorators.cache
    
11.     options:
    
12.         members:
    
13.             - method_deco_cache
    
14.             - singleton_refresh_regular

复制代码

运行与构建

执行 mkdocs serve 后可通过http://127.0.0.1:8000/访问；
执行 mkdocs build --clean 可以构建生成网站site目录，可以将site添加到.gitignore文件中；
site目录中的html、js等文件可用于自行部署成文档服务网站。

部署

免费开源的部署，一般有两个选择：

• Github Pages
  
  
  
  • 发布到GitHub Pages的说明；
    
  • 限制：每个用户只能免费新建一个按照自己账号名称命名的pages；
    
  
  
• readthedocs网站
  
  
  
  • 支持
    1. Sphinx

    复制代码
    和
    1. MkDocs

    复制代码
    两种方式的部署；
    
  • 相关配置说明；
    
  • 对开源项目文档免费使用；
    
  • 使用该种方式托管文档，必须使用
    1. readthedocs

    复制代码
    的主题；
    
  
  

本文使用了

1. readthedocs

复制代码

网站托管，网站可以使用Github账号登录，即可同步github项目信息，便捷导入生成文档。
部署需要依赖配置文件

1. .readthedocs.yaml

复制代码

, 内容示例如下：

1. version: 2
   
2. 
   
3. # 构建文档需要的环境
   
4. build:
   
5.   os: ubuntu-22.04
   
6.   tools:
   
7.     python: "3.9"
   
8. 
   
9. # 文档工具相关配置
   
10. mkdocs:
    
11.   configuration: mkdocs.yml
    
12. 
    
13. # 安装依赖
    
14. python:
    
15.   install:
    
16.   - requirements: requirements_docs.txt  # 自己维护在项目中的依赖文件

复制代码

具体导入步骤根据同步的GitHub项目列表，参考指引提示即可完成；
到此这篇关于python使用MkDocs自动生成文档的操作方法的文章就介绍到这了,更多相关python MkDocs生成文档内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

来源:https://www.jb51.net/python/322080rmm.htm
免责声明：由于采集信息均来自互联网，如果侵犯了您的权益，请联系我们【E-Mail:cb@itdo.tech】 我们会及时删除侵权内容，谢谢合作！