文档框架
同博客框架 WordPress、Hexo 等一样，Web 文档也有自己的框架，如比如 Java 的 Javadoc，Python 的 pydoc，以及Python-sphinx。对于 Python 有专门文档标记语言 reStructuredText（RST），常见的 Python 各种库和工具的帮助文档基本都是用 RST 所写。如 Requests、Flask、Scrapy 等。
不过，用 RST 编写对于已经会了 Markdown（更为流行） 的读者来说，有点浪费，而且两者的语法差异较大，容易造成记忆冲突。幸运的是有了 mkdocs，不仅能轻松制作类似 Scrapy 帮助文档的文档项目，而且支持 markdown 语法。
使用MkDocs
安装 MkDocs
pip install mkdocs
创建项目
执行下面命令就在当前目录下，生成一个 testdocs 文件夹，就是创建的文档项目
mkdocs new testdocs
cd命令进入文件夹，查看结构
- mkdocs.yml 为配置文件
- docs 文件夹中为文档文件目录，文件使用 markdown 编写
文档预览
进入 创建的文档项目目录，执行 mkdocs serve：
mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
INFO - Documentation built in 0.16 seconds
INFO - [18:16:18] Serving on http://127.0.0.1:8000/
将启动一个 Web 服务器，用于预览 testdocs 文件项目，效果如下：
进行配置
mkdocs 的配置简单明了，采用 yml 格式：
site_name: MkLorum
site_url: https://example.com/
nav:
- Home: 'index.md'
- About: 'markdown.md'
theme: readthedocs
当文档比较复杂时，可以通过嵌套的方式对 nav 进行配置，例如在 Home 下还有子菜单，menu1 和 menu2：
nav:
- Home: 'index.md'
- 'User Guide':
- 'Writing your docs':
- Menu1 : 'menu1.md'
- Menu2 : 'menu2.md'
- 'Styling your docs': './style/styling-your-docs.md'
- About:
- 'License': 'license.md'
- 'Release Notes': 'release-notes.md'
效果如下：
- 如果菜单名中有空格需要用引号(单双皆可)括起来
- 文档文件不要同导航结构配合，可以为导航配置相对文件路径
- 菜单层级可以无限嵌套
默认情况下，即在不配置导航 (nav) 的情况下，会按照文件名，目录结构生成导航菜单
更换主题
下载主题：
pip install mkdocs-material mkdocs-windmill
mkdocs.yml里添加:
theme:
name: 'material'
# 也可以选bootstrap
其他的一些配置：
theme:
name: "material"
# logo: 'images/logo.svg'
logo:
icon: "mkdocs"
palette:
primary: "black"
accent: "deep orange"
language: "zh"
material页面风格：
更多主题：https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes
一些约定
- 站点首页 默认情况下，必须创建一个 index.md 作为站点首页。同时也支持 README.md 作为首页，会将其转化为 index.html。如果 index.md 和 README.md 同时存在，将忽略 README.md
- 非 markdown 文件 markdown 文件，即扩展名为 md 的文件，会被转化为 html。非 markdown 文件，会被原封拷贝，不做任何修改
- 内部链接 如果需要引用另一个文件，只需要按照 markdown 链接的方式，连接到这个文件就可以了，例如
[详情请参考](./detail.md)。不要担心文件名，因为生成站点时会自动换成 html 文件路径
生成站点
执行mkdocs build命令，生成站点，点击index.html即可
mkdocs build
使用sphinx
安装sphinx和主题
pip install sphinx sphinx_rtd_theme
创建项目
创建一个文件夹后，执行命令
sphinx-quickstart
编写文档
修改主题
在conf.py文件中添加这两行代码，修改主题
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
# 记得删除下面的html_theme = 'alabaster'
更多主题请参考：https://sphinx-themes.org/
构建站点
在根目录输入命令，即可生成网站构建。在build/html目录下即可看到生成的网站
make html
点击index.html即可查看
使用Teadocs
https://blog.csdn.net/qq_37608398/article/details/90636928
站点发布
可以通过nginx进行发布，同时也可以通过Read the Docs在线发布，它是一个专门为文档而生的 Web 服务，可以便捷地发布文档，只需要注册一个账号。商业版可以发布私有文档，否则只能发布公开的文档。
官网地址：https://readthedocs.org/dashboard/
Read the Docs 支持 mkdocs 创建的文档项目，即，意味着不需要对 mkdocs 项目进行生成站点操作，就可以发布，这样就方便多了。只需要在发布前，创建一个 Read the Docs 配置文件 .readthedocs.yml 就可以了。
# Required
version: 2
mkdocs:
configuration: mkdocs.yml
# Optionally set the version of Python and requirements required to build your docs
python:
version: 3.7
install:
- requirements: docs/requirements.txt
mkdocs用于指定文档使用 mkdocs 编写configuration指定 mkdocs 文档项目的配置文件python为可选项，如果文档需要 python 运行环境的话可以配置，如不需要可以不配置
更多配置请参考：https://docs.readthedocs.io/en/stable/config-file/v2.html
然后将 mkdocs 项目用 github 做版本管理，这是因为 Read the Docs 目前只支持通过 github 导入文件。最后在 Read the Docs 的 Add Projcet 中
选择 Github 中的对应库，按照说明操作即可
如果顺利将会获得一个文档的访问网址。