使用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