wip

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 <https://www.netlify.com/>`__
-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 <https://www.netlify.com/>`__ 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 <fbgemm-gpu.example.reference>` from another page
+  :ref:`custom text <docs.example.reference>` from another page
   in the docs.
 
   Note that the prefix underscore is not needed when referencing the anchor.

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