文档¶
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 --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
部署预览¶
当提交拉取请求时，Netlify 将自动构建和部署 FBGEMM 和 FBGEMM_GPU 文档的预览。构建完成后，可以在以下位置找到部署预览
https://deploy-preview-{PR NUMBER}--pytorch-fbgemm-docs.netlify.app/
