如何在本地构建与预览文档#

Warning

文档构建有 FULL 和 MINI 两种不同的模式，可以通过配置环境变量 MGE_DOC_MODE 来决定具体的行为， 该环境变量提供以下三种选项：

AUTO （默认）

自动探测 MegEngine 包是否可用，如可用则进入 FULL 模式，否则进入 MINI 模式；

MINI

构建除 MegEngine API Reference 外的文档，不依赖于 MegEngine 源代码 。

FULL

构建全部文档，包括 MegEngine API Reference, 需要设置好 MegEngine 路径。

Note

  • 下面以 Ubuntu 18.04 + Python 3.8 环境为例，向你展示从无到有构建 MegEngine 文档的过程；

  • 具有 sudo 特权的用户，可以使用 scripts/bootstrap.sh 脚本自动完成环境准备。

克隆文档源码到本地#

将存储库克隆到本地（默认为 main 分支），确保目录下有 Makefile 文件：

git clone https://github.com/MegEngine/Documentation
cd Documentation

对于一些旧版本的 Git, 还需要用下面的命令从 GitHub LFS 服务器拉取对应文件：

git lfs install
git lfs pull

Note

为确保正常克隆，需要在环境中安装好 LFS (Large File Storage) 插件。

初始化第三方依赖#

git submodule update --init --progress --depth=1 --recursive

这一步将会拉取文档所依赖的第三方子模块，比如文档所用的主题（在后面的步骤中会进行安装）。

指定 MegEngine 路径（可选）#

在构建文档时，会尝试执行 import megengine 和 import megenginelite 来判断使用 FULL 还是 MINI 模式。在检测到本地环境没有 MegEngine 时， 将采用 MINI 模式，该模式将跳过所有 API 文档页面的生成， 同时也会忽略掉一些警告信息的检查，因此它仅适用于修改幅度极其小的情况（如单页面，不存在交叉引用等）。 在绝大部分情况下，推荐使用 FULL 模式，以便进行完整的文档内容生成和语法、样式检查。

根据不同的需求，有两种方式将用于构建文档的 MegEngine 导入当前 Python 环境（任选其一即可）：

  • 如果你是框架用户，不需要改动 MegEngine 源码，只想在本地完整地构建和预览所有文档的内容， 或进行简单的增删查改，建议安装最新发布的 MegEngine 稳定版 Wheel 包。 可以直接使用对应的 pip intall 命令将已经打包好的 MegEngine 安装到当前的 Python 环境中。 ➡️ 了解如何进行使用 pip 安装 。

  • 如果你是研发人员，需要在指定的 MegEngine 分支源代码上生成对应文档，则需要克隆对应分支进行编译构建。 通过 export PYTHONPATH 的形式来临时指定特定源代码路径，例如：

    export PYTHONPATH=/data/MegEngine/imperative/python:$PYTHONPATH
export PYTHONPATH=/data/MegEngine/lite/pylite:$PYTHONPATH

    同时需要手动安装 MegEngine Python Package 的依赖文件：

    python3 -m pip install -r /data/MegEngine/imperative/python/requires.txt

    注意一定要使用版本一致的 MegEngine 与 Lite , 否则可能导致产生符号冲突。 这种方式适合开发者需要同时对源码和文档进行维护的情况。➡️ 了解如何进行从源码构建 。

安装 Sphinx 与 Pydata 主题#

MegEngine 文档使用 Sphinx 进行整个网站的构建，请运行下面的指令，安装 Sphinx 和相关依赖：

python3 -m pip install -r requirements.txt

Warning

MegEgnine 文档使用了 Fork 后修改过的 pydata-sphinx-theme 主题， 如果你的本地环境已经存在该主题，可能需要提前删除该主题或使用额外的 Python 虚拟环境。

安装相关软件包#

Pandoc 转换工具#

nbsphinx 是 Sphinx 的一个插件，可以帮助我们对 .ipynb 格式的 Jupyter Notebook 文件进行解析。

我们在安装依赖环境时已经安装好了 nbsphinx, 但还需要通过依赖项目 Pandoc 来支持转换 Markdown 格式。

如果你使用的是是 Ubuntu（Debian）操作系统，可以直接使用 apt 命令进行安装 Pandoc:

sudo apt install -y pandoc

如果你使用的是其它操作系统，想要安装 Pandoc，请参考 Pandoc 官方的 Installing 页面。

Graphviz 绘图工具#

Graphviz 是非常流行的图形可视化软件，在 MegEngine 文档中经常会用它制作一些可视化图片。

如果你使用的是 Ubuntu（Debian）操作系统，可以直接使用 apt 命令进行安装 Graphviz:

sudo apt install -y graphviz

如果你使用的是其它操作系统，想要安装 Graphviz，请参考 Graphviz 官方的 Download 页面。

使用 Sphinx 进行文档构建#

  1. 运行 make help 指令，可看到相应的帮助和参数信息；

  2. 在文档目录下使用 make html 指令，会在 build 目录下生成 HTML 文件夹。

  3. 文档生成成功后，打开 build/html/index.html 文件便可访问主页。

Note

Sphinx 默认支持增量构建，当你再次执行 make html 时将仅对变化的文件进行更新；

Warning

Sphinx 不会检测增量模式下非文档文件的更改，例如主题文件、静态文件和与 autodoc 一起使用的源代码； 如果发现一些页面的元素仍被缓存而没有被更新，请尝试通过传入 -a 参数禁用增量模式（但构建速度会相应地变慢）， 或者通过 make clean 指令清除掉已经构建出的内容。

自动构建和实时预览页面#

你也可以使用 make livehtml 指令，在监测到文件变化时自动重新构建，而且可以通过浏览器进行实时的预览。 其中 HOST 参数默认为 127.0.0.1, PORT 参数默认为 8000, 可人为指定：

make livehtml AUTOBUILDOPTS="--host 0.0.0.0 --port 1124"

运行上面这个代码将得到类似的实时监控输出：

[I 210723 15:35:07 server:335] Serving on http://0.0.0.0:1124
[I 210723 15:35:07 handlers:62] Start watching changes
[I 210723 15:35:07 handlers:64] Start detecting changes

Note

背后的原理是：我们使用了 sphinx-autobuild 对原有 sphinx-build 进行了增强。