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