企业官网建设流程全解析

ManimGL 如何在本地构建官方 Sphinx 文档并查看构建产物

【免费下载链接】manimAnimation engine for explanatory math videos项目地址: https://gitcode.com/GitHub_Trending/ma/manim

ManimGL（本仓库，3Blue1Brown 使用的 OpenGL 版本 manim）把官方文档的完整 RST 源文件放在docs/source/下，并用 Sphinx 构建。如果你想在自己的机器上生成这套文档——例如修改.rst页面后预览效果，或核对文档构建流程——官方给出的路径是：安装文档依赖，进入docs/目录执行make html，产物落在docs/build/html/。完整说明见 How to build this documentation。

准备条件：安装文档构建依赖

文档构建不要求安装 ManimGL 本体，只需安装docs/目录下单独维护的依赖清单 docs/requirements.txt：

pip install -r docs/requirements.txt

该清单固定了四个包，且注释明确说明版本上限是有意为之：

Sphinx>=8,<10 furo>=2024.8 sphinx-copybutton>=0.5,<1 Jinja2>=3.1,<4

清单里的注释指出：这个构建此前把 Sphinx 钉在 3.0.3 而没限制 Jinja2，结果在 Jinja2 3.1 移除environmentfilter时构建就坏了，所以这些上限要“有意识地调整，而不是任由漂移”。升级这些包之前先看这个注释。

构建：在 docs/ 目录执行 make html

构建入口是 docs/Makefile。它把SOURCEDIR固定为source、BUILDDIR固定为build，SPHINXBUILD默认为sphinx-build，所有未知目标都通过 catch-all 规则转发给sphinx-build -M <目标> source build。因此make html实际执行的就是标准 Sphinx 的 HTML 构建。

按 贡献文档说明 给出的步骤，在仓库根目录依次执行：

pip install -r docs/requirements.txt cd docs/ make html

Makefile 顶部注释说明：SPHINXOPTS等变量既可以从命令行传入，也可以从环境变量（前两个）传入，$(O)是SPHINXOPTS的快捷写法。需要追加 sphinx-build 参数时，就用这种方式传给make，而不用修改 Makefile。

make不带参数时执行help目标，列出 Sphinx 可用的构建目标，可以在构建前先确认环境：

cd docs/ make

Windows 下的替代路径

docs/make.bat 是 Makefile 的 Windows 对应物，sphinx-build调用方式和目录约定与 Makefile 一致。没有参数时它同样只显示帮助；要构建 HTML：

make.bat html

如果环境中找不到sphinx-build，make.bat 会直接终止（exit /b 1）并打印类似如下的提示（引自 make.bat 原文）：

The 'sphinx-build' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the 'sphinx-build' executable. Alternatively you may add the Sphinx directory to PATH.

出现这条提示时的处理办法就是文档给出的两条：安装 Sphinx（即执行上面的pip install -r docs/requirements.txt），或通过SPHINXBUILD环境变量指向sphinx-build可执行文件的完整路径。

查看构建产物

按 贡献文档说明 的原文，构建完成后：

The output document is located in docs/build/html/

即 HTML 文档输出在仓库的docs/build/html/目录，用浏览器打开该目录即可查看构建出来的文档站点。

两个与产物显示相关的配置事实，来自 docs/source/conf.py：

• 主题使用furo，因此本地构建出的页面外观与官方线上一致的前提是 furo 已按清单装上；
• conf.py用sys.path.insert(0, os.path.abspath('../../'))把仓库根目录加进了导入路径，并且html_logo引用的是../../logo/transparent_graph.png。这也解释了为什么构建必须按文档流程先cd docs/再执行——相对路径是相对docs/目录解析的，换个位置执行会破坏这些引用。

限制与边界

• 版本约束以 docs/requirements.txt 为准（Sphinx 8 到小于 10、Jinja2 3.1 到小于 4），不要自行放宽，理由见文件内注释。
• 文档构建部分只描述了html目标的使用；Makefile 的 catch-all 规则意味着其他 Sphinx-M目标（如make不带参数时 help 列出的目标）也能转发，但官方文档没有对它们给出说明或预期产物，以实际输出为准。
• 如果修改了docs/source/下的 RST 文件，仓库文档没有给出“增量重建”或缓存清理的专门说明，重新执行make html即可获得新的docs/build/html/产物。

【免费下载链接】manimAnimation engine for explanatory math videos项目地址: https://gitcode.com/GitHub_Trending/ma/manim