MkDocs (Python 虚拟环境)¶

简介¶

为 Rocky Linux 创建文档的过程的一个方面是验证您的新文档在发布之前是否正确显示。

本指南的目的是提供一些建议，以便在专门为此目的而创建的本地 Python 环境中执行此任务。

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

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

开发 Python 应用程序时出现的一个问题是，实现用于开发的 Python 实例与系统解释器的隔离。隔离防止了用于安装 Python 应用程序的模块与主机系统上安装的模块之间发生不兼容。

已经有一些优秀的指南使用容器来隔离 Python 解释器。但是，这些指南暗示了解各种容器化技术。

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

要求¶

正在运行的 Rocky Linux 副本
正确安装的 python 包
熟悉命令行
活动的互联网连接

准备环境¶

该环境提供了一个根文件夹，其中包含两个必需的 Rocky Linux GitHub 存储库和 MkDocs 将运行的文件夹，以及在其中进行初始化和运行您的 Python 副本的文件夹。

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

mkdir -p ~/lab/rockydocs/env

Python 虚拟环境¶

要创建 Python 的副本（MkDocs 将在其中运行），请使用为此目的专门开发的模块，即 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 命令没有添加任何后缀，因为这指的是 bash shell，即 Rocky Linux 的默认 shell。此时，您的 shell 提示符 应为

(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]$

如您所见，停用后，终端提示符已恢复到系统提示符。在运行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'

您首先需要在docs.rockylinux.org中创建一个docs文件夹，然后在其中链接您从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