# Read The Doc + Mkdocs 

## Mkdocs 配置和使用

MkDocs是一个快速、简单、华丽的静态网站生成器，适用于构建项目文档。文档源文件以Markdown编写，并使用一个YAML文件来进行配置。 MkDocs生成完全静态的HTML网站，你可以将其部署到GitHub pages、Amzzon S3或你自己选择的其它任意地方。

- 官方地址：[https://www.mkdocs.org/](https://link.zhihu.com/?target=https%3A//www.mkdocs.org/)

  MkDocs有一堆很好看的主题。 官方内置了两个主题： [mkdocs](https://link.zhihu.com/?target=https%3A//mkdocs.zimoapps.com/user-guide/styling-your-docs/%23mkdocs) 和[readthedocs](https://link.zhihu.com/?target=https%3A//mkdocs.zimoapps.com/user-guide/styling-your-docs/%23readthedocs)， 也可以从[MkDocs wiki](https://link.zhihu.com/?target=https%3A//github.com/mkdocs/mkdocs/wiki/MkDocs-Themes)中选择第三方主题， 或者[自定义主题](https://link.zhihu.com/?target=https%3A//mkdocs.zimoapps.com/user-guide/custom-themes/)。

### 要求

MkDocs 需要在您的系统上安装最新版本的[Python](https://www.python.org/)和 Python 包管理器[pip 。](https://pip.readthedocs.io/en/stable/installing/)

~~~note
您可能需要编辑PATH环境变量以包含Scripts Python 安装目录。
~~~



您可以通过命令行检查是否已安装这些：

~~~sh
$ python --version
Python 3.11.5
$ pip --version
# 这里我使用的虚拟环境
D:\Virtualenvs\cggroup\Lib\site-packages\pip (python 3.11)
~~~

### 安装 MkDocs

~~~sh
# 安装mkDocs
$ pip install mkdocs
# 查看版本
$ mkdocs --version
mkdocs, version 1.3.0 from D:\Virtualenvs\cggroup\Lib\site-packages\mkdocs (Python 3.11)
~~~

### 手动创建新项目

具体学习在 [MkDocs官方文档](https://www.mkdocs.org/getting-started/#creating-a-new-project)，这里就不再赘述。



### 快速搭建

使用基础模版

访问 [example-mkdocs-basic](https://github.com/readthedocs-examples/example-mkdocs-basic) 仓库

![image-20230916221543032](images/image-20230916221543032-16948737443851.png)

~~~sh
# git这个仓库 
$ git clone git@github.com:readthedocs-examples/example-mkdocs-basic.git

Cloning into 'example-mkdocs-basic'...
remote: Enumerating objects: 82, done.
remote: Counting objects: 100% (19/19), done.
remote: Compressing objects: 100% (5/5), done.
remote: Total 82 (delta 15), reused 14 (delta 14), pack-reused 63
Receiving objects:  69% (57/82), 28.00 KiB | 31.00 KiB/s
Receiving objects: 100% (82/82), 32.08 KiB | 50.00 KiB/s, done.
Resolving deltas: 100% (32/32), done.

$ cd example-mkdocs-basic
~~~

#### 配置环境并运行

~~~sh
# 创建python虚拟环境
$ mkvirtualenv cgwiki

created virtual environment CPython3.11.5.final.0-64 in 4468ms
  creator CPython3Windows(dest=D:\Virtualenvs\cgwiki, clear=False, no_vcs_ignore=False, global=False)
  seeder FromAppData(download=False, pip=bundle, setuptools=bundle, wheel=bundle, via=copy, app_data_dir=C:\Users\zz\AppData\Local\pypa\virtualenv)
    added seed packages: pip==23.2.1, setuptools==68.2.0, wheel==0.41.2
  activators BashActivator,BatchActivator,FishActivator,NushellActivator,PowerShellActivator,PythonActivator

# 安装mkdocs库
(cgwiki) $ pip install mkdocs
# 进入example-mkdocs-basic
(cgwiki) $ cd example-mkdocs-basic
# 安装依赖包
(cgwiki) $ pip install -r docs/requirements.txt

# 运行
(cgwiki) $ mkdocs serve


~~~

此时使用浏览器访问 [http://127.0.0.1:8000/](http://127.0.0.1:8000/)

![image-20230916223651907](images/image-20230916223651907.png)

#### 配置mkdocs.yml

~~~yml
site_name: 站点名称 #站点名称
site_author: #站点作者
repo_url: # gitee /github 等仓库位置
edit_uri: blob/master/docs/
copyright: # 版权信息

theme:
  name: readthedocs
  highlightjs: true
plugins:
  - search
  - mkdocstrings:
      handlers:
        # See: https://mkdocstrings.github.io/python/usage/
        python:
          options:
            docstring_style: sphinx
markdown_extensions:
  - markdown_include.include:
      base_path: .
  - admonition

~~~

配置好基本信息后重新启动 mkdocs

~~~sh
# 运行
(cgwiki) $ mkdocs serve
~~~

#### 文档存放

进入docs文件夹中，删除md文件，存放自己的文件即可

![image-20230916224839735](images/image-20230916224839735.png)

也可以根据情况创建文件夹，mydocs会根据文件夹层级与md文件自动适配导航（路由）

当然mkdocs.yml 中可以配置nav，详情见官网

配置完成后更改文件名称即可，更改git仓库后，push到自己的仓库中即可

### 配置主题

**[第三方主题]**(https://mkdocs-like-code.readthedocs.io/zh_CN/latest/MkDocs-advanced-operations/theme-configuration/#_3)"



## ReadTheDoc托管MkDocs

### 导入项目

注册[ReadTheDoc](https://readthedocs.org/)

注册好后导入自己的代码库，如图

![image-20230916230356000](images/image-20230916230356000.png)

![image-20230916230503881](images/image-20230916230503881.png)

![image-20230916230740654](images/image-20230916230740654.png)

**这里要注意的是，如果你更改了requirements.txt文档的路径，此时一定要同时更新位置.否则无法托管**



.readthedocs.yaml

~~~yaml
# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the version of Python and other tools you might need
# build:
#   os: ubuntu-22.04
#   tools:
#     python: "3.10"

mkdocs:
  configuration: mkdocs.yml

# Optionally declare the Python requirements required to build your docs
python:
   install:
   - requirements: docs/requirements.txt # 如果移动依赖文件，这里一定要对应到正确的路径中
~~~

点击完成后，稍等几分钟即可构建

![image-20230916231142095](images/image-20230916231142095.png)

当然可以点击正在构建您的文件，查看进度

![image-20230916231409024](images/image-20230916231409024.png)

构建完成后，点击阅读文档

![image-20230916231709894](images/image-20230916231709894.png)



### 创建钩子

创建项目集成的钩子，目的是在我们更新git仓库的时候，ReadTheDocs自动帮我们重新托管文档，不用自己手动building

操作如图

![image-20230916232209395](images/image-20230916232209395.png)

![image-20230916232242987](images/image-20230916232242987.png)

![image-20230916232313623](images/image-20230916232313623.png)



![image-20230916232419175](images/image-20230916232419175.png)

复制上面的路径，粘贴到 仓库webHooks管理中，如图

​	![image-20230916232536097](images/image-20230916232536097.png)

![image-20230916232826219](images/image-20230916232826219.png)

**添加后即可，将来更新仓库后，ReadTheDoc会自动创建新的托管文档**