Documentation

Both FBGEMM and FBGEMM_GPU provide extensive comments in its source files, which serve as the most authoritative and up-to-date documentation available for the two libraries.

General Documentation Guidelines

When new public API methods are added, they should be accompanied by sufficient documentation. Here are some guidelines for documenting FBGEMM and FBGEMM_GPU code:

• Code by itself is not documentation! Put yourself in the shoes of new developers who has to understand what your code does, and make their lives easier.

• Documentation should be added for any and all public API methods.

• Don’t leave documentation as a separate task. Instead, write docstrings together with the code.

• At a very minimum, add:

  • A description of the method.

  • A description of the parameters and arguments that can be passed to the method.

  • A description of the method’s return value.

  • Usage examples, links to other methods, and method invocation limitations.

Specific Documentation Guides

• Adding Documentation to C++ Code
• Adding Documentation to Python Code
• Adding Documentation to Auto-Generated Python Code
• Sphinx Documentation Pointers

Building the Documentation

Note: The most up-to-date documentation build instructions are embedded in a set of scripts bundled in the FBGEMM repo under setup_env.bash.

The general steps for building the FBGEMM and FBGEMM_GPU documentation are as follows:

1. Set up an isolated build environment.

2. Build FBGEMM_GPU (CPU variant).

3. Set up the documentation toolchain.

4. Run documentation build scripts.

Set Up Build Environment

Follow the instructions for setting up the Conda environment at Set Up an Isolated Build Environment.

Build FBGEMM_GPU

A build pass of FBGEMM_GPU is required for the documentation to be built correctly. Follow the instructions in Install the Build Tools, followed by CPU-Only Build, to build FBGEMM_GPU (CPU variant).

Set Up the Documentation Toolchain

# !! 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

Build the Documentation

# Generate the C++ documentation, the Python documentation, and assemble
# together
make clean doxygen html

After the build completes, view the generated documentation:

sphinx-serve -b build

Linting the Documentation

The same command used for building can be used for linting, by prepending the SPHINX_LINT flag:

SPHINX_LINT=1 make clean doxygen html

For technical reasons, running a Sphinx build with linting turned on will cause the documentation to be assembled incorrectly, which is why linting is invoked separately from the build.

Occasionally, unresolved references might show up while linting, which have the following error signature:

/opt/build/repo/fbgemm_gpu/docs/docstring of torch._ops.fbgemm.PyCapsule.jagged_2d_to_dense:1:py:class reference target not found: Tensor

If these errors turn out to be false negatives, they can be silenced by being added into the nitpick.ignore file (in the same directory as Sphinx conf.py):

# Add in `{domain} {reference}` format, with space in between.
py:class Tensor

Deployment Preview

A preview of the FBGEMM and FBGEMM_GPU documentation will be automatically built and deployed by Netlify when pull requests are made. When the build completes, the deployment preview can be found at:

https://deploy-preview-{PR NUMBER}--pytorch-fbgemm-docs.netlify.app/