构建文档¶

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

必需的依赖项¶

你可以在本地机器上安装依赖项，或者你可以构建一个包含这些依赖项的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/

然后使用 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/zh-cn/windows/wsl/install

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

如果你想在Windows文件系统中将提示符中的目录更改为SymPy的工作文件夹，可以在Windows中的文件路径前加上 cd /mnt/，然后在你的shell中运行以导航到该文件夹。（还要注意，Linux使用 / 而不是 \ 作为文件路径。）

与Cygwin或MSYS2相比，这种方法提供了更好的兼容性，并且比虚拟机更方便，如果你在工作中部分需要Linux环境，然而这种方法仅适用于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 发布页面上。

如果在 GitHub Actions 上构建 PDF 文档失败，99% 的情况下这是由于 LaTeX 数学格式错误导致的。请仔细检查您添加的任何数学公式是否格式正确，并确保使用 双反引号 来表示代码（\(单反引号\) 会渲染为数学公式，而不是代码）。有关 LaTeX 数学格式化的提示，请参阅样式指南中的资源。

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

在 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 字体，右键点击并选择 为所有用户安装。

要生成PDF文档，请运行:

cd doc

make pdf

生成的PDF将在:

_build/latex/sympy-<version>.pdf

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