MkDocs (Python 虚拟环境)¶

简介¶

创建 Rocky Linux 文档过程中，一个重要方面是出版前验证新文档是否显示正确。

本指南的目的是提供一些建议，用于在专门为此目的设置的本地 Python 环境中执行此任务。

Rocky Linux 的文档使用 Markdown 语言编写，通常转换为其他格式。Markdown 语法简洁，尤其适合编写技术文档。

在我们的例子中，文档使用 Python 应用程序转换为 HTML，该应用程序负责构建静态站点。开发人员使用的应用程序是 MkDocs。

Python 应用程序开发过程中出现的一个问题是，需要实现开发所用的 Python 实例与系统解释器的隔离。这种隔离可防止安装 Python 应用程序所需的模块与主机系统上安装的模块之间出现不兼容。

已经有一些很好的指南使用容器来隔离 Python 解释器。然而，这些指南需要了解各种容器化技术。

本指南使用 Rocky Linux 的 python 包提供的 venv 模块进行分离。此模块在 3.6 版本以后的所有新版 Python 中都可用。这将直接实现系统上 Python 解释器的隔离，而无需安装和配置新的“系统”。

要求¶

运行中的 Rocky Linux 副本
已正确安装 python 包
熟悉命令行
有效的互联网连接

准备环境¶

环境提供一个根文件夹，其中包含两个必需的 Rocky Linux GitHub 仓库以及初始化和在虚拟环境中运行您的 Python 副本的文件夹。

首先，创建将包含所有其他内容的文件夹，并在此基础上，也创建 MkDocs 将运行的 env 文件夹

mkdir -p ~/lab/rockydocs/env

Python 虚拟环境¶

要创建用于运行 MkDocs 的 Python 副本，请使用为此目的专门开发的模块，即 Python venv 模块。这允许创建一个虚拟环境，该环境源自系统中安装的环境，并且完全隔离且独立。

这将允许我们在单独的文件夹中拥有一个解释器副本，其中仅包含 MkDocs 运行 Rocky Linux 文档所需的包。

转到刚刚创建的文件夹 (rockydocs) 并使用以下命令创建虚拟环境：

cd ~/lab/rockydocs/
python -m venv env

该命令将用一系列文件夹和文件填充您的 env 文件夹，这些文件和文件夹模仿您的系统 python 树，如下所示：

env/
├── bin
│   ├── activate
│   ├── activate.csh
│   ├── activate.fish
│   ├── Activate.ps1
│   ├── pip
│   ├── pip3
│   ├── pip3.11
│   ├── python -> /usr/bin/python
│   ├── python3 -> python
│   └── python3.11 -> python
├── include
│   └── python3.11
├── lib
│   └── python3.11
├── lib64 -> lib
└── pyvenv.cfg

正如您所见，虚拟环境使用的 Python 解释器仍然是系统中可用的解释器 python -> /usr/bin/python。虚拟化过程仅负责隔离您的实例。

激活虚拟环境¶

在结构中列出的文件中有几个名为 activate 的文件用于此目的。每个文件的后缀指示相关的 shell。

激活会将此 Python 实例与系统 Python 实例分离，并允许我们在没有干扰的情况下进行文档开发。要激活它，请转到 env 文件夹并运行命令：

[rocky_user@rl9 rockydocs]$ cd ~/lab/rockydocs/env/
[rocky_user@rl9 env]$ source ./bin/activate

发出 activate 命令时没有加任何后缀，因为这是指 Rocky Linux 的默认 shell bash。此时，您的 shell prompt 应该如下所示：

(env) [rocky_user@rl9 env]$

如您所见，开头的 (env) 部分表示您现在处于虚拟环境中。此时要做的第一件事是更新 pip，即用于安装 MkDocs 的 Python 模块管理器。为此，请使用以下命令：

python -m pip install --upgrade pip

python -m pip install --upgrade pip
Requirement already satisfied: pip in ./lib/python3.9/site-packages (21.2.3)
Collecting pip
  Downloading pip-23.1-py3-none-any.whl (2.1 MB)
    |████████████████████████████████| 2.1 MB 1.6 MB/s
Installing collected packages: pip
  Attempting uninstall: pip
    Found existing installation: pip 21.2.3
    Uninstalling pip-21.2.3:
      Successfully uninstalled pip-21.2.3
Successfully installed pip-23.1

退出环境¶

要退出虚拟环境，请使用 deactivate 命令：

(env) [rocky_user@rl9 env]$ deactivate
[rocky_user@rl9 env]$

正如您所见，在停用后，终端 prompt 已恢复为系统提示符。在运行 MkDocs 安装及后续命令之前，您应始终仔细检查提示符。检查此项将避免不必要的、不需要的全局应用程序安装，以及遗漏 mkdocs serve 的运行。

下载仓库¶

现在您已经了解了如何创建虚拟环境以及如何管理它，您可以开始准备所有必需的物品。

要实现 Rocky Linux 文档的本地版本，需要两个仓库：文档仓库 documentation 和站点结构仓库 docs.rockylinux.org。这些内容从 Rocky Linux GitHub 下载。

首先克隆站点结构仓库到 rockydocs 文件夹：

cd ~/lab/rockydocs/
git clone https://github.com/rocky-linux/docs.rockylinux.org.git

在此文件夹中，有两个文件将用于构建本地文档。它们是 mkdocs.yml，用于初始化 MkDocs 的配置文件，以及 requirement.txt，其中包含安装 mkdocs 所需的所有 Python 包。

完成后，您还需要下载文档仓库：

git clone https://github.com/rocky-linux/documentation.git

此时，您将在 rockydocs 文件夹中拥有以下结构：

rockydocs/
├── env
├── docs.rockylinux.org
├── documentation

总而言之，您可以说 env 文件夹将是您的 MkDocs 引擎，它将使用 docs.rockylinux.org 作为容器来显示 documentation 中包含的数据。

安装 MkDocs¶

如前所述，Rocky Linux 的开发人员提供了 requirement.txt 文件，其中包含运行自定义 MkDocs 实例所需的模块列表。您将使用此文件一次性安装所有必需项。

首先，进入您的 Python 虚拟环境：

[rocky_user@rl9 rockydocs]$ cd ~/lab/rockydocs/env/
[rocky_user@rl9 env]$ source ./bin/activate
(env) [rocky_user@rl9 env]$

接下来，使用以下命令继续安装 MkDocs 及其所有组件：

(env) [rocky_user@rl9 env]$ python -m pip install -r ../docs.rockylinux.org/requirements.txt

要检查一切是否正常，您可以调用 MkDocs 帮助，这也会向我们介绍可用的命令：

(env) [rocky_user@rl9 env]$ mkdocs -h
Usage: mkdocs [OPTIONS] COMMAND [ARGS]...

  MkDocs - Project documentation with Markdown.

Options:
  -V, --version  Show the version and exit.
  -q, --quiet    Silence warnings
  -v, --verbose  Enable verbose output
  -h, --help     Show this message and exit.

Commands:
  build      Build the MkDocs documentation
  gh-deploy  Deploy your documentation to GitHub Pages
  new        Create a new MkDocs project
  serve      Run the builtin development server

如果一切按计划进行，您可以退出虚拟环境并开始准备必要的连接。

(env) [rocky_user@rl9 env]$ deactivate
[rocky_user@rl9 env]$

链接文档¶

现在一切都已准备就绪，您必须将文档仓库链接到 docs.rockylinux.org 容器站点内。遵循 mkdocs.yml 中定义的设置：

docs_dir: 'docs/docs'

您首先需要 a docs 文件夹 in docs.rockylinux.org，然后从其中链接 documentation 仓库中的 docs 文件夹。

cd ~/lab/rockydocs/docs.rockylinux.org
mkdir docs
cd docs/
ln -s ../../documentation/docs/ docs

启动本地文档¶

您已准备好启动 Rocky Linux 文档的本地副本。首先，您需要启动 Python 虚拟环境，然后使用 docs.rockylinux.org/mkdocs.yml 中定义的设置初始化您的 MkDocs 实例。

此文件包含本地化、功能和主题管理的所有设置。

该网站 UI 的开发人员选择了 Material for MkDocs 主题，该主题提供了比默认 MkDocs 主题更多的附加功能和自定义。

执行以下命令：

[rocky_user@rl9 rockydocs]$ cd ~/lab/rockydocs/env/
[rocky_user@rl9 rockydocs]$ source ./bin/activate
(env) [rocky_user@rl9 env]$ mkdocs serve -f ../docs.rockylinux.org/mkdocs.yml

您应该会在终端中看到站点构建的开始。显示将显示 MkDocs 发现的任何错误，例如丢失的链接或其他问题。

INFO     -  Building documentation...
INFO     -  Adding 'de' to the 'plugins.search.lang' option
INFO     -  Adding 'fr' to the 'plugins.search.lang' option
INFO     -  Adding 'es' to the 'plugins.search.lang' option
INFO     -  Adding 'it' to the 'plugins.search.lang' option
INFO     -  Adding 'ja' to the 'plugins.search.lang' option
...
...
INFO     -  Documentation built in 102.59 seconds
INFO     -  [11:46:50] Watching paths for changes:
            '/home/rocky_user/lab/rockydocs/docs.rockylinux.org/docs/docs',
            '/home/rocky_user/lab/rockydocs/docs.rockylinux.org/mkdocs.yml'
INFO     -  [11:46:50] Serving on http://127.0.0.1:8000/

当您在浏览器中打开指定地址 http://127.0.0.1:8000 时，您将运行您的文档站点副本。此副本在功能和结构上完美地镜像了在线站点，让您可以评估您的页面在站点上的外观和影响。

MkDocs 包含一种机制，用于检查 docs_dir 路径指定的文件夹中的文件更改，并且在 documentation/docs 中插入新页面或修改现有页面将被自动识别并生成新的静态站点构建。

由于 MkDocs 构建静态站点可能需要数分钟时间，因此建议在编写或插入页面之前仔细检查该页面。这样可以避免仅仅因为您忘记了标点符号等而等待站点构建。

退出开发环境¶

一旦您对新页面的显示感到满意，就可以退出开发环境。这包括首先退出 MkDocs，然后停用 Python 虚拟环境。要退出 MkDocs，您需要使用按键组合 Ctrl + C，如上所示，要退出虚拟环境，您需要调用 deactivate 命令。

...
INFO     -  [22:32:41] Serving on http://127.0.0.1:8000/
^CINFO     -  Shutting down...
(env) [rocky_user@rl9 env]$
(env) [rocky_user@rl9 env]$ deactivate
[rocky_user@rl9 env]$

为 venv 方法创建别名¶

您可以创建一个 bash 别名来加快使用 venv 方法提供 mkdocs 的过程。

运行以下命令将别名 venv 添加到您的 .bash_profile 文件中：

printf "# mkdocs alias\nalias venv='source $HOME/lab/rockydocs/env/bin/activate && mkdocs serve -f $HOME/lab/rockydocs/docs.rockylinux.org/mkdocs.yml'" >> ~/.bash_profile

使用新创建的别名更新 shell 环境：

source ~/.bash_profile

现在，您可以使用 venv 命令创建使用 venv 方法的 mkdocs 本地开发站点：

venv

您仍然需要运行 deactivate 来退出虚拟环境。

deactivate

结论和最终想法¶

在本地开发站点中验证您的新页面，可以确保您的工作始终符合在线文档站点，从而使我们能够做出最佳贡献。

文档的合规性也为文档站点的策展人提供了极大的帮助，他们之后只需处理内容的正误。

总而言之，可以说这种方法允许在不依赖容器化的前提下满足“干净”安装 MkDocs 的要求。

作者：Franco Colussi

贡献者：Steven Spencer, Ganna Zhyrnova