Read The Doc + Mkdocs

Mkdocs 配置和使用

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

官方地址：https://www.mkdocs.org/

MkDocs有一堆很好看的主题。官方内置了两个主题： mkdocs 和readthedocs，也可以从MkDocs wiki中选择第三方主题，或者自定义主题。

要求

MkDocs 需要在您的系统上安装最新版本的Python和 Python 包管理器pip 。

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

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

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

安装 MkDocs

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

手动创建新项目

具体学习在 MkDocs官方文档，这里就不再赘述。

快速搭建

使用基础模版

访问 example-mkdocs-basic 仓库

# 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

配置环境并运行

# 创建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/

配置mkdocs.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

# 运行
(cgwiki) $ mkdocs serve

文档存放

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

也可以根据情况创建文件夹，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

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

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

.readthedocs.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 # 如果移动依赖文件，这里一定要对应到正确的路径中