网站超市源码哪个好,wordpress louie,制作医院网站,深圳市宝安区松岗python使用MkDocs自动生成文档 前言使用MkDocs环境相关资料使用介绍项目结构配置文件注释生成文档的配置运行与构建部署 实践的项目 前言
python代码注释风格有很多#xff0c;比较主流的有 reStructuredText风格、numpy风格、Google风格。
自动生成文档的工具也有很多… python使用MkDocs自动生成文档 前言使用MkDocs环境相关资料使用介绍项目结构配置文件注释生成文档的配置运行与构建部署 实践的项目 前言
python代码注释风格有很多比较主流的有 reStructuredText风格、numpy风格、Google风格。
自动生成文档的工具也有很多常见的有
Pydocs python环境自带支持MarkDown但功能比较简单Sphinx 非常流行默认支持reStructuredText风格注释若要支持MarkDown需要扩展插件支持MkDocs 优势是能够很好的支持MarkDown格式来组织文档支持Google风格注释;
对于熟悉MarkDown语法的人来说推荐使用MkDocs使用起来很方便。
使用MkDocs
环境
python3.9安装依赖
mkdocs1.6.0
mkdocstrings0.25.1
mkdocstrings-python1.10.3
mkdocs-autorefs1.0.1
mkdocs-material9.5.24
mkdocs-same-dir0.1.3相关资料
MkDocs 主要文档核心库MkDocs配套的mkdocstrings 负责从代码中提取注释形成文档 yaml配置中插件mkdocstrings的options配置可以好好查看文档说明mkdocs.yml配置是全局生效在注释生成配置各个类中也可以单独配置 Google 开源项目风格指南 – 中文版mkdocs-autorefs 可以在文档中使用超链定位到其他位置mkdocs-material 文档主题风格插件 Material for MkDocs 是效果最好且持续更新的若不需要material风格可以不需要该插件MkDocs 官方内置了两个主题 mkdocs 和 readthedocs当然mkdocs也支持自定义主题风格 一般情况下无需自己定义有开源插件支持 mkdocs-same-dir 该插件可以解决访问项目根目录下README.md的问题 mkdocs默认寻找docs目录下的MarkDown文件
使用介绍
记得提前安装相关依赖。
项目结构
截取部分展示
├── 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: materiallanguage: 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: pythonhandlers:python:# 配置解析代码注释的路径paths: [pykit_tools]options:heading_level: 3 # 使用了三级菜单在docs/Reference.md文档中会有体现show_root_heading: trueshow_symbol_type_heading: trueshow_source: falseselection:docstring_style: google
注释生成文档的配置
配置文件中 options 配置详见 mkdocstrings globallocal-options
示例配置docs/Reference.md (截取部分) 其中:::是特定格式配置类或者函数的python模块路径
# 使用(Usage)## 装饰器
::: decorators.commonoptions: # 会覆盖全局配置members:- handle_exception- time_record::: decorators.cacheoptions:members:- method_deco_cache- 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网站 支持 Sphinx 和 MkDocs 两种方式的部署相关配置说明对开源项目文档免费使用使用该种方式托管文档必须使用readthedocs的主题
本文使用了readthedocs网站托管网站可以使用Github账号登录即可同步github项目信息便捷导入生成文档。
部署需要依赖配置文件.readthedocs.yaml, 内容示例如下
version: 2# 构建文档需要的环境
build:os: ubuntu-22.04tools:python: 3.9# 文档工具相关配置
mkdocs:configuration: mkdocs.yml# 安装依赖
python:install:- requirements: requirements_docs.txt # 自己维护在项目中的依赖文件具体导入步骤根据同步的GitHub项目列表参考指引提示即可完成 也可以参考文档 文件托管系统-ReadtheDocs 。
实践的项目
代码地址https://github.com/SkylerHu/pykit-tools文档地址https://pykit-tools.readthedocs.io
