使用Mkdocs生成项目文档
MkDocs是一个基于Python的静态站点生成器，它可以将Markdown格式的文档转换为漂亮的静态网站。MkDocs提供了一种简单而灵活的方式来创建文档，并支持多种主题和插件。
下面是一个简单的示例代码，演示如何使用MkDocs创建一个文档站点：
安装MkDocs
可以使用pip命令安装MkDocs：
pip install mkdocs
初始化项目
使用mkdocs new命令初始化MkDocs项目，该命令会生成一个包含配置文件和目录结构的项目：
在项目根目录，命令行中使用mkdocs new来初始化文档。
$ python3 -m mkdocs new .
INFO - Writing config file: ./mkdocs.yml
INFO - Writing initial docs: ./docs/index.md
执行后在项目中生成docs目录及mkdocs.yml配置文件，如下图所示：
编写文档
在docs目录下修改index.md，并新建其他Markdown格式的文档，如下图：
配置mkdocs.yml
在mkdocs.yml中配置站点名称、描述、作者、url、导航菜单等信息等。
- site_name：站点名称
- site_url：站点 URL 链接
- site_author：站点作者
- site_description：站点描述
- copyright：版权信息
- repo_url：站点仓库 URL
- nav: 站点导航
- theme: 站点主题
- markdown_extensions: Markdown扩展
参考配置如下：
site_name: Python-YApi
site_description: Python Client for YApi base on HTTP apis.
site_author: Han Zhichao
site_url: http://localhost:8000
copyright: Copyright @ 2023 Han Zhichao, All rights reserved.
repo_url: https://github.com/hanzhichao/python-yapi
theme: mkdocs # 默认主题
nav:
- 首页: index.md
- 安装方法: install.md
- 使用方法: usage.md
- 模块列表:
- 项目管理: modules/project.md
- 接口管理: modules/interface.md
- 作者说明: author.md
所有文件的引用都是相对与docs目录，支持菜单及引用子目录文件，如“模块列表”。
预览站点
使用mkdocs serve命令预览站点，例如：
$ python3 -m mkdocs serve
该命令会启动一个本地服务器，可以在浏览器中访问http://localhost:8000 来查看站点，如下图：
生成站点
使用mkdocs build命令生成静态站点，例如：
$ python3 -m mkdocs build
该命令会生成静态站点文件，保存在site目录下。
使用其他主题
在mkdocs.yml配置文件中使用theme可以指定主题(默认主题为mkdocs)。
使用readthedocs主题
修改mkdocs.yml，添加主题配置
theme: readthedocs
刷新页面或重新mkdocs build，效果如下：
使用material主题
安装mkdocs-material
pip install mkdocs-material
修改mkdocs.yml配置
theme: material
刷新页面或重新mkdocs build，效果如下：
添加markdown扩展
常用的扩展有toc、footnotes,tables、checklist等，其中checklist支持需要安装三方插件
pip install markdown-checklist
在mkdocs.yml中添加markdown扩展配置，参考如下：
markdown_extensions:
- toc:
permalink: True
- footnotes
- tables
- markdown_checklist.extension
这样便可以在文档使用使用[toc]，- [ ] 等支持了。
MkDocs还提供了丰富的配置选项和插件，可以根据需要进行定制。你可以参考MkDocs官方文档，了解更多详细信息和用法示例。
参考：https://sspai.com/prime/story/mkdocs-primer
参考：https://www.mkdocs.org/user-guide
