文档¶
FBGEMM 和 FBGEMM_GPU 的源代码中都提供了丰富的注释，这些注释是这两个库最权威和最新的文档。
通用文档指南¶
在添加新的公共 API 方法时，应附带足够的文档。以下是为 FBGEMM 和 FBGEMM_GPU 代码编写文档的一些指南
代码本身不是文档！ 设身处地为需要理解你的代码的新开发者着想，让他们更容易上手。
应为所有公共 API 方法添加文档。
不要将文档作为单独的任务留到以后。相反，请与代码一起编写 docstrings。
至少应包含：
方法的描述。
可传递给方法的参数和实参的描述。
方法返回值的描述。
使用示例、指向其他方法的链接以及方法调用限制。
特定文档指南¶
构建文档¶
注意： 最新文档构建说明已嵌入 FBGEMM 仓库中 setup_env.bash 下的一组脚本中。
构建 FBGEMM 和 FBGEMM_GPU 文档的一般步骤如下：
设置独立的构建环境。
构建 FBGEMM_GPU（CPU 变体）。
设置文档工具链。
运行文档构建脚本。
设置构建环境¶
按照 设置独立的构建环境 中的说明设置 Conda 环境。
构建 FBGEMM_GPU¶
为了正确构建文档，需要进行一次 FBGEMM_GPU 构建。请按照 安装构建工具 中的说明，然后按照 仅限 CPU 构建 的说明构建 FBGEMM_GPU（CPU 变体）。
设置文档工具链¶
# !! Run inside the Conda environment !!
# From the /fbgemm_gpu/ directory
cd docs
# Install Sphinx and other Python packages
pip install -r requirements.txt
# Install Doxygen and and other tools
conda install -c conda-forge --override-channels -y \
doxygen \
graphviz \
make
构建文档¶
# Generate the C++ documentation, the Python documentation, and assemble
# together
make clean doxygen html
构建完成后，查看生成的文档
sphinx-serve -b build
检查文档¶
用于构建的相同命令也可用于检查，只需在命令前加上 SPHINX_LINT 标志即可
SPHINX_LINT=1 make clean doxygen html
出于技术原因，在启用检查的情况下运行 Sphinx 构建会导致文档组装不正确，这就是为什么检查与构建分开调用的原因。
偶尔，检查时可能会出现未解析的引用，其错误特征如下：
/opt/build/repo/fbgemm_gpu/docs/docstring of torch._ops.fbgemm.PyCapsule.jagged_2d_to_dense:1:py:class reference target not found: Tensor
如果这些错误是误报，则可以通过将它们添加到 nitpick.ignore 文件（与 Sphinx conf.py 位于同一目录下）来忽略它们
# Add in `{domain} {reference}` format, with space in between.
py:class Tensor
部署预览¶
当创建拉取请求时，FBGEMM 和 FBGEMM_GPU 文档的预览将由 Netlify 自动构建和部署。构建完成后，可以在以下位置找到部署预览：
https://deploy-preview-{PR NUMBER}--pytorch-fbgemm-docs.netlify.app/
