diff --git a/fbgemm_gpu/docs/src/general/Documentation.rst b/fbgemm_gpu/docs/src/general/Documentation.rst
index e3d5603ed9..fc2278d1e0 100644
--- a/fbgemm_gpu/docs/src/general/Documentation.rst
+++ b/fbgemm_gpu/docs/src/general/Documentation.rst
@@ -6,7 +6,7 @@ serve as the most authoritative and up-to-date documentation available for the
two libraries.
-.. _fbgemm-gpu.docs.build:
+.. _general.docs.build:
Building the Documentation
--------------------------
@@ -79,18 +79,33 @@ The same command used for building can be used for linting, by prepending the
SPHINX_LINT=1 make clean doxygen html
-Note that for technical reasons, running the Sphinx build with linting turned on
-will cause the documentation to be assembled incorrectly, which is why linting
-is invoked separately.
+For technical reasons, running the 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:
+
+.. code:: sh
+
+ /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``):
+
+.. code:: yaml
+
+ # Add in `{domain} {reference}` format, with space in between.
+ py:class Tensor
Deployment Preview
~~~~~~~~~~~~~~~~~~
-As a PyTorch project, 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:
+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:
.. code:: sh
@@ -123,6 +138,8 @@ code:
* Add usage examples, links to other methods, and method invocation limitations.
+.. _general.docs.add.python:
+
Adding Documentation to Python Code
-----------------------------------
@@ -167,7 +184,7 @@ docstring:
``index.rst`` (e.g. :ref:`fbgemm-gpu.toc.api.python`).
#. Verify the changes by building the docs locally with
- :ref:`fbgemm-gpu.docs.build` or submitting a PR for a Netlify preview.
+ :ref:`general.docs.build` or submitting a PR for a Netlify preview.
------------
@@ -178,21 +195,31 @@ The Python docstring example above generates the following HTML output:
------------
+.. _general.docs.add.autogen:
+
Adding Documentation to Auto-Generated Python Code
--------------------------------------------------
-SomeDocumentation for Python is provided through docstrings and generated using
+Many FBGEMM_GPU Python API methods are auto-generated through PyTorch during the
+build process, and require docstrings to be attached after the fact. Follow
+these instructions to document auto-generated Python methods:
-#. Add the docstring directly under the name of the target method. At a very
- minimum, please add descriptions of:
+#. If needed, create a Python file under ``fbgemm_gpu/fbgemm_gpu/docs`` in the
+ repo.
+
+#. Use the provided helper methods to add attach a docstring to the target
+ auto-generated method by method name. Here is an example from the codebase:
+
+ .. literalinclude:: ../../../fbgemm_gpu/docs/jagged_tensor_ops.py
+ :language: python
+ :start-after: fbgemm-gpu.autogen.docs.examples.docstring.start
+ :end-before: fbgemm-gpu.autogen.docs.examples.docstring.end
- Here is an example Python docstring:
+#. Follow the instructions in :ref:`general.docs.add.python` to render the
+ docstring in the documentation.
- .. literalinclude:: ../../../fbgemm_gpu/docs/jagged_tensor_ops.py
- :language: python
- :start-after: fbgemm-gpu.autogen.docs.examples.docstring.start
- :end-before: fbgemm-gpu.autogen.docs.examples.docstring.end
+.. _general.docs.add.cpp:
Adding Documentation to C++ Code
--------------------------------
@@ -260,7 +287,7 @@ docstring:
append the directory path to the parameter.
#. Verify the changes by building the docs locally with
- :ref:`fbgemm-gpu.docs.build` or submitting a PR for a Netlify preview.
+ :ref:`general.docs.build` or submitting a PR for a Netlify preview.
------------
@@ -283,7 +310,7 @@ created above the target section:
.. code:: rst
- .. _fbgemm-gpu.example.reference:
+ .. _docs.example.reference:
Example Section Header
----------------------
@@ -298,11 +325,11 @@ The anchor can then be referenced elsewhere in the docs:
.. code:: rst
- Referencing the section :ref:`fbgemm-gpu.example.reference` from
+ Referencing the section :ref:`docs.example.reference` from
another page in the docs.
Referencing the section with
- :ref:`custom text ` from another page
+ :ref:`custom text ` from another page
in the docs.
Note that the prefix underscore is not needed when referencing the anchor.
diff --git a/fbgemm_gpu/docs/src/nitpick.ignore b/fbgemm_gpu/docs/src/nitpick.ignore
index 10617e9b28..061ad72816 100644
--- a/fbgemm_gpu/docs/src/nitpick.ignore
+++ b/fbgemm_gpu/docs/src/nitpick.ignore
@@ -40,5 +40,5 @@ py:class optional
py:class PoolingMode
py:class RecordCacheMetrics
py:class SparseType
-# py:class Tensor
+py:class Tensor
py:class WeightDecayMode