文档¶
FBGEMM 和 FBGEMM_GPU 都在其源文件中提供了广泛的注释，这些注释是两个库的最权威和最新的文档。
通用文档指南¶
添加新的公共 API 方法时，应附带足够的文档。以下是 FBGEMM 和 FBGEMM_GPU 代码文档化的一些指南
**代码本身不是文档！** 换位思考，想象一下新开发人员需要了解您的代码的功能，帮助他们更轻松地理解代码。
应为所有公共 API 方法添加文档。
不要将文档作为单独的任务。相反，应该与代码一起编写文档字符串。
至少添加
方法的描述。
可以传递给方法的参数和参数的描述。
方法返回值的描述。
使用示例、指向其他方法的链接以及方法调用限制。
特定文档指南¶
构建文档¶
**注意：** 最新文档构建说明已嵌入到 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 -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
部署预览¶
当创建拉取请求时，Netlify 会自动构建和部署 FBGEMM 和 FBGEMM_GPU 文档的预览版。构建完成后，可以在以下地址找到部署预览：
https://deploy-preview-{PR NUMBER}--pytorch-fbgemm-docs.netlify.app/
