文档生成器

在构建软件项目时，简单的，我们直接在项目主页上，直接创建一个 README.md 文件即可。
但是，对于复杂点的项目或者工程，我们经常需要提供完善的操作手册或开发文档。
一个 README.md 就显得力不从心了。我们需要一份完整，丰富的文档手册。

在 python 世界里，mkdocs 和 sphinx 是文档生成器里面比较流行的。

案例

• sphinx(readthedocs.org): requests, flask, scrapy, python官方文档
• mkdocs(readthedocs.org): fastapi

安装

pip install mkdocs
mkdocs -V
mkdocs, version 1.1.2 from C:\Users\...
pip install -U mkdocs
pip uninstall mkdocs

命令

mkdocs [OPTIONS] COMMAND [ARGS]...

Commands:
  build      生成HTML静态文件
  gh-deploy  部署到 GitHub Pages
  new        创建一个新的 MkDocs 项目
  serve      开启本地预览

快速开始

    mkdocs new mkdocdemo
    cd mkdocdemo
    mkdocs serve

在浏览器打开 http://127.0.0.1:8000/ 即可预览网页。

修改默认端口

    mkdocs serve -a 127.0.0.1:8891
    mkdocs serve --dev-addr=127.0.0.1:8888

项目设置

配置文件 mkdocs.yml 。除了site_name 配置项之外，其他都是可选的。

修改主题

内置主题 只需在 mkdocs.yml 文件中添加 theme 配置选项。
如 readthedocs, mkdocs

    site_name: MkLorum
    theme: readthedocs

第三方主题，先要安装才可以使用。
我们来看一下 FastAPI 的文档主题 mkdocs material, 这个主题在 GitHub 非常火爆。

    pip install mkdocs-material

mkdocs.yml:

    site_name: CatMES
    repo_url: https://gitee.com/whq78164/UeditorAsset
    repo_name: whq78164/UeditorAsset
    nav:
        - 首页: index.md
        - 关于我们: about.md
        - 'test.md'
    theme:
        name: "material"
        logo: "https://www.baidu.com/img/flexible/logo/pc/result.png"
        language: "zh"

添加页面

在 docs 目录中添加 test.md
修改配置文件 mkdocs.yml

site_name: Markdown指南
nav:
- 首页: index.md
- 测试: test.md

生成站点

mkdocs build

build构建命令，会在根目录，即 mkdocs.yml 文件的同级目录下，生成site目录。该目录包含所有的HTML静态文件。
使用 mkdocs build --clean 可以在构建时清理一些残留资源。

MkDocs 快速入门 https://blog.csdn.net/wirelessqa/article/details/78173401
使用mkdocs搭建博客和编写文档 https://new.qq.com/rain/a/20201227a074px00
sphinx https://www.sphinx-doc.org/en/master/
mkdocs https://www.mkdocs.org/
精选python软件库 https://python.libhunt.com/