开发和构建文档

要构建文档，你需要Sphinx和一些其他软件包。

设置文档环境

使用 mamba 或 conda (推荐)

首先创建一个名为ipywidgets_docs的conda environment以安装所有必要的包：

# create the environment
mamba env update --file docs/environment.yml

然后，激活环境。

# activate the environment
conda activate ipywidgets_docs   # Linux and OS X
activate ipywidgets_docs         # Windows

使用 pip

另外，也可以通过以下命令创建虚拟环境并激活它：

# create the environment
python -m venv .

# activate the environment
source bin/activate

在环境中，安装这些包：

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

提示

构建文档网站需要一个可工作的 nodejs 安装，可以通过您选择的包管理器安装，或直接从 NodeJS website 安装。

构建文档

安装所需软件包后，您可以通过以下方式构建文档：

cd docs/source
sphinx-build -T -E -b html -d ../build/doctrees -D language=en . ../build/html

之后，生成的HTML文件将在 build/html/index.html处可用。你可以在终端中输入以下内容在浏览器中查看文档： open build/html/index.html。或者， 你可以启动内置的Python网络服务器：

cd docs/build/html
python3 -m http.server -b 127.0,0.1

… 并导航到 http://localhost:8000/。

您还应该查看 Project Jupyter Documentation Guide。

观看文档

也可以启动一个监控源代码并自动重新构建的Web服务器：

cd docs/source
sphinx-autobuild -T -E -b html -d ../build/doctrees -D language=en . ../build/html

… 并导航到 http://localhost:8000/。

清理笔记本输出以生成文档

在使用笔记本源文件生成文档时，最好在提交笔记本前使用nbstripout去除笔记本输出和元数据。例如，以下命令将去除笔记本中的所有输出：

nbstripout "docs/source/examples/Widget List.ipynb"