构建文档¶

首先安装文档所需的依赖关系。

所需依赖关系¶

您可以选择在本地机器上安装依赖关系，也可以构建包含它们的 Docker 镜像。

Docker¶

如果您有 Docker，那么您可以选择构建 Docker 镜像，而不是按照下面给出的特定于操作系统的安装说明进行操作。

cd doc

docker build -f Dockerfile.htmldoc -t sympy_htmldoc .

如果您选择此选项，现在可以跳到下面的“构建文档”部分。

Debian/Ubuntu¶

对于 Debian/Ubuntu

apt-get install python3-sphinx texlive-latex-recommended dvipng librsvg2-bin imagemagick docbook2x graphviz

使用以下命令安装 pip

sudo apt install python3-pip

但是，您也可以创建一个虚拟环境并在其中使用 pip，使用以下命令

python3 -m venv /path/to/my/venv  # create the venv

然后使用以下命令激活它

source /path/to/my/venv/bin/activate  # need to rerun this each time you open a new terminal

通过以上两种方法中的任何一种安装 pip 后，运行以下命令

python -m pip install -r doc/requirements.txt

如果您遇到 mpmath 错误，请安装 python-mpmath 包

apt-get install python-mpmath

如果您遇到 matplotlib 错误，请安装 python-matplotlib 包

apt-get install python-matplotlib

Fedora¶

对于 Fedora（以及其他基于 RPM 的发行版），安装先决条件

dnf install python3-sphinx librsvg2 ImageMagick docbook2X texlive-dvipng-bin

texlive-scheme-medium librsvg2-tools

python -m pip install -r doc/requirements.txt

如果您遇到 mpmath 错误，请安装 python3-mpmath 包

dnf install python3-mpmath

如果您遇到 matplotlib 错误，请安装 python3-matplotlib 包

dnf install python3-matplotlib

Mac¶

对于 Mac，首先安装 homebrew: https://brew.sh.cn/

然后使用 homebrew 安装这些包

brew install imagemagick graphviz docbook librsvg

使用 pip 或 conda 安装文档依赖关系

python -m pip install -r requirements.txt

或者

conda install -c conda-forge --file requirements.txt

在 Windows 系统上使 Sphinx 构建成功很困难，因为某些依赖项（如 dvipng 或 docbook2x）不可用。

Windows 10¶

然而，对于 Windows 10，Windows Subsystem for Linux 可以作为一个可能的变通解决方案，您可以在按照以下教程操作后在您的 Windows 系统上安装 Ubuntu shell。

https://learn.microsoft.com/en-us/windows/wsl/install

在您的命令提示符中，运行 ubuntu 切换到 Linux 终端，并按照上面的 Debian/Ubuntu 教程安装依赖项，然后您可以运行 make html 来构建。 (注意，您还需要通过 apt-get install make 安装 make。)

如果您想将您的命令提示符中的目录更改为 Windows 文件系统中 SymPy 的工作文件夹，您可以在 Windows 中的文件路径前加上 cd /mnt/，并在您的 shell 中运行以导航到该文件夹。 (另请注意，Linux 使用 / 而不是 \ 作为文件路径。)

如果您在工作流程中部分需要 Linux 环境，这种方法比 Cygwin 或 MSYS2 提供更好的兼容性，比虚拟机更方便，但这种方法只适用于 Windows 10 64 位用户。

或者

按照说明安装 Chocolatey

安装 make 和其他依赖项

choco install make graphviz rsvg-convert imagemagick

安装 python 依赖项

pip install -r doc/requirements.txt

构建文档¶

Docker¶

如果您选择使用 Docker 构建，并按照上述说明构建了 sympy_htmldoc 镜像，那么您可以使用以下命令构建文档

docker run --rm -v /absolute/path/to/sympy:/sympy sympy_htmldoc

(请确保将 sympy 的实际绝对文件系统路径替换掉！) 此命令可以在任何目录中运行。

本地安装¶

如果您选择按照上面的操作系统特定说明进行操作并在本地安装了必需的依赖项，则可以通过在 doc 子目录中运行 makefile 来构建文档

cd doc

make html

查看文档¶

构建完文档后，生成的文档将在 doc/_build/html 下找到。要在您喜欢的网络浏览器中查看它们，请使用下拉菜单并选择“打开文件”，导航到 sympy/doc/_build/html 文件夹，并打开 index.html 文件。

使用实时服务器自动重建¶

上面给出的说明告诉您如何构建一次文档，并在浏览器中加载它们。在您对文档源代码进行更改后，您需要手动重复构建步骤，并在浏览器中重新加载页面。

有一个替代方法是设置一个实时服务器，它将监视文档目录，在检测到更改时自动重建，并在浏览器中自动重新加载您正在查看的页面。

如果您想使用此选项，该过程将再次取决于您是使用 Docker 还是本地安装。

Docker¶

要使用 Docker 启动实时服务器，您可以使用

docker run --rm -it \
     -v /absolute/path/to/sympy:/sympy \
     -p 8000:80 \
     sympy_htmldoc live

然后将您的浏览器导航到 localhost:8000。您可以通过更改命令中的 8000 来使用不同的端口。再次，请确保将 sympy 的实际绝对文件系统路径替换掉。

完成后，您可以在终端中使用 ctrl-c 停止服务器。

或者，您可以在分离模式下运行服务器，使用

docker run --rm -d --name=sympy-livehtml \
     -v /absolute/path/to/sympy:/sympy \
     -p 8000:80 \
     sympy_htmldoc live

然后使用以下命令停止它

docker stop sympy-livehtml

本地安装¶

如果您在本地安装了构建依赖项，则只需使用

cd doc

make livehtml

启动服务器。您的网络浏览器应该自动打开一个新标签页，显示 SymPy 文档的索引页。

完成后，您可以在终端中使用 ctrl-c 停止服务器。

PDF 文档¶

注意

大多数贡献者不需要构建 PDF 文档。PDF 文档将在拉取请求时在 GitHub Actions 上自动构建。每个版本的 PDF 文档都包含在 GitHub 版本页面上。

如果 PDF 文档构建在 GitHub Actions 上失败，99% 的情况下这是由于 LaTeX 数学格式错误。仔细检查您添加的任何数学是否格式正确，并确保您对代码使用“双反引号”（`single backticks` 将呈现为数学，而不是代码）。有关 LaTeX 数学格式的提示，请参阅样式指南中的资源。

构建 PDF 文档需要一些额外的依赖项。首先，您需要有一个包含 XeLaTeX 和 latexmk 的 TeXLive 安装。您还需要安装 Chrome 或 Chromium，因为它用于转换一些 SVG 文件以供 PDF 使用。

在 Ubuntu 上，您可以使用以下命令安装它们

apt-get install chromium-browser texlive texlive-xetex texlive-fonts-recommended texlive-latex-extra latexmk lmodern

在 Mac 上，您可以使用

brew install texlive

brew install --cask chromium

brew tap homebrew/cask-fonts

brew install font-dejavu

在 Windows 10 上，您可以使用

choco install chromium strawberryperl miktex dejavufonts

如果 DejaVu 字体未安装在 C:\Windows\Fonts 中，则打开 ~\AppData\Local\Microsoft\Windows\Fonts，选择所有 DejaVu 字体，右键单击并单击 Install for all users。

要构建 pdf 文档，请运行

cd doc

make pdf

生成的 PDF 将在

_build/latex/sympy-<version>.pdf

其中 <version> 是 SymPy 版本（例如，sympy-1.10.dev.pdf）。