Re-structure the Python documentation (pytorch#2239)

Summary: - Re-structure the Python documentation Pull Request resolved: pytorch#2239 Reviewed By: spcyppt Differential Revision: D52495567 Pulled By: q10 fbshipit-source-id: a46406c8755c61cee0dae6d6e06805f5f31f6afd
q10 · Jan 3, 2024 · 441697c · 441697c
1 parent 905ff66
commit 441697c
Show file tree

Hide file tree

Showing 16 changed files with 318 additions and 361 deletions.
diff --git a/.github/scripts/fbgemm_gpu_build.bash b/.github/scripts/fbgemm_gpu_build.bash
@@ -420,6 +420,7 @@ build_fbgemm_gpu_install () {
   # fbgemm_gpu/ subdirectory present
   cd - || return 1
   (test_python_import_package "${env_name}" fbgemm_gpu) || return 1
+  (test_python_import_symbol "${env_name}" fbgemm_gpu __version__) || return 1
   cd - || return 1
 
   echo "[BUILD] FBGEMM-GPU build + install completed"

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,27 +1,32 @@
-# Contributing to FBGEMM
+# Contributing to FBGEMM / FBGEMM_GPU
+
 We want to make contributing to this project as easy and transparent as
 possible.
 
 ## Code of Conduct
+
 The code of conduct is described in [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).
 
 ## Pull Requests
+
 We actively welcome your pull requests.
 
-1. Fork the repo and create your branch from `main`.
+1. **Fork** the repository and create your branch from `main`.
 2. If you've added code that should be tested, add tests.
-3. If you've changed APIs, update the documentation.
+3. If you've added or changed APIs, update the documentation.
 4. Ensure the test suite passes.
 5. Make sure your code lints.
 6. If you haven't already, complete the Contributor License Agreement ("CLA").
 
 ## Contributor License Agreement ("CLA")
+
 In order to accept your pull request, we need you to submit a CLA. You only need
 to do this once to work on any of Facebook's open source projects.
 
 Complete your CLA here: <https://code.facebook.com/cla>
 
 ## Issues
+
 We use GitHub issues to track public bugs. Please ensure your description is
 clear and has sufficient instructions to be able to reproduce the issue.
 
@@ -30,5 +35,6 @@ disclosure of security bugs. In those cases, please go through the process
 outlined on that page and do not file a public issue.
 
 ## License
+
 By contributing to FBGEMM, you agree that your contributions will be licensed
 under the LICENSE file in the root directory of this source tree.
diff --git a/fbgemm_gpu/docs/src/conf.py b/fbgemm_gpu/docs/src/conf.py
@@ -52,6 +52,7 @@
     "myst_parser",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosectionlabel",
+    "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
     "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",

diff --git a/fbgemm_gpu/docs/src/general/ContactInfo.rst b/fbgemm_gpu/docs/src/general/ContactInfo.rst
diff --git a/fbgemm_gpu/docs/src/general/ContactUs.rst b/fbgemm_gpu/docs/src/general/ContactUs.rst
@@ -0,0 +1,17 @@
+Contact Us
+==========
+
+GitHub
+------
+
+*  `GitHub Issues <https://github.com/pytorch/FBGEMM/issues>`__: Use this to file
+   questions, issues, and feature requests concerning FBGEMM_GPU.
+
+*  `GitHub Discussions <https://github.com/pytorch/FBGEMM/discussions>`__: Use
+   avenuue to kick off longer discussions regarding FBGEMM_GPU.
+
+Slack
+-----
+
+Feel free to reach out to us on the ``#fbgemm`` channel in
+`Pytorch Slack <https://bit.ly/ptslack>`__.
diff --git a/fbgemm_gpu/docs/src/general/Contributing.rst b/fbgemm_gpu/docs/src/general/Contributing.rst
@@ -0,0 +1,2 @@
+.. include:: ../../../../CONTRIBUTING.md
+   :parser: myst_parser.sphinx_
diff --git a/fbgemm_gpu/docs/src/general/DocsInstructions.rst b/fbgemm_gpu/docs/src/general/DocsInstructions.rst
@@ -1,5 +1,5 @@
-Contributing Documentation
-==========================
+Building Documentation
+======================
 
 FBGEMM_GPU provides extensive comments in its source files, which provide the
 most authoritative and up-to-date documentation available for the package.
@@ -170,7 +170,8 @@ When you add descriptionss to a function, make sure that the ``#ifndef`` and
 ``#endif`` are configured correctly.
 
 All functions are grouped by a specific group for better organization.
-Make sure you add ``@defgroup`` to the code comments.
+Make sure you add ``@defgroup`` to the code comments to define the group, and
+``@ingroup`` in each docstring to associate the target method with the group.
 
 Follow these instructions to document, generate, and publish a new C++
 description:

diff --git a/fbgemm_gpu/docs/src/index.rst b/fbgemm_gpu/docs/src/index.rst
@@ -19,6 +19,8 @@ library.
    general/InstallationInstructions.rst
    general/TestInstructions.rst
    general/DocsInstructions.rst
+   general/Contributing.rst
+   general/ContactUs.rst
 
 .. _fbgemm-gpu.docs.toc.overview:
 

diff --git a/fbgemm_gpu/docs/src/overview/jagged-tensor-ops/JaggedTensorOps.rst b/fbgemm_gpu/docs/src/overview/jagged-tensor-ops/JaggedTensorOps.rst
@@ -24,7 +24,7 @@ Jagged Tensor Format
 -------------------
 
 Jagged tensors are effectively represented in FBGEMm_GPU as a three-tensor
-object.  The three tensors are: **Values**, **Max Lengths**, and **Offsets**.
+object.  The three tensors are: **Values**, **MaxLengths**, and **Offsets**.
 
 Values
 ~~~~~~

diff --git a/fbgemm_gpu/docs/src/python-api/jagged_tensor_ops.rst b/fbgemm_gpu/docs/src/python-api/jagged_tensor_ops.rst
@@ -1,37 +1,24 @@
 Jagged Tensor Operators
 =======================
 
-.. automodule:: fbgemm_gpu
-
-
 .. autofunction:: torch.ops.fbgemm.jagged_2d_to_dense
 
-
 .. autofunction:: torch.ops.fbgemm.jagged_1d_to_dense
 
-
 .. autofunction:: torch.ops.fbgemm.dense_to_jagged
 
-
 .. autofunction:: torch.ops.fbgemm.jagged_to_padded_dense
 
-
 .. autofunction:: torch.ops.fbgemm.jagged_dense_elementwise_add
 
-
 .. autofunction:: torch.ops.fbgemm.jagged_dense_elementwise_add_jagged_output
 
-
 .. autofunction:: torch.ops.fbgemm.jagged_dense_dense_elementwise_add_jagged_output
 
-
 .. autofunction:: torch.ops.fbgemm.jagged_dense_elementwise_mul
 
-
 .. autofunction:: torch.ops.fbgemm.batched_dense_vec_jagged_2d_mul
 
-
 .. autofunction:: torch.ops.fbgemm.stacked_jagged_1d_to_dense
 
-
 .. autofunction:: torch.ops.fbgemm.stacked_jagged_2d_to_dense
diff --git a/fbgemm_gpu/fbgemm_gpu/__init__.py b/fbgemm_gpu/fbgemm_gpu/__init__.py
@@ -14,13 +14,15 @@
 except Exception as e:
     print(e)
 
-# __init__.py is only used in OSS
-# Use existence to check if fbgemm_gpu_py.so has already been loaded
+# Since __init__.py is only used in OSS context, we define `open_source` here
+# and use its existence to determine whether or not we are in OSS context
 open_source: bool = True
 
-# Re-export docs
-# Trigger meta registrations
-from . import _fbgemm_gpu_docs, sparse_ops  # noqa: F401, E402  # noqa: F401, E402
+# Trigger the manual addition of docstrings to pybind11-generated operators
+import fbgemm_gpu.docs  # noqa: F401, E402
 
-# Re-export the version string from the auto-generated version file
-from ._fbgemm_gpu_version import __version__  # noqa: F401, E402
+# Export the version string from the version file auto-generated by setup.py
+from fbgemm_gpu.docs.version import __version__  # noqa: F401, E402
+
+# Trigger meta operator registrations
+from . import sparse_ops  # noqa: F401, E402
diff --git a/fbgemm_gpu/fbgemm_gpu/docs/__init__.py b/fbgemm_gpu/fbgemm_gpu/docs/__init__.py
@@ -4,3 +4,6 @@
 #
 # This source code is licensed under the BSD-style license found in the
 # LICENSE file in the root directory of this source tree.
+
+# Trigger the manual addition of docstrings to pybind11-generated operators
+from . import jagged_tensor_ops, table_batched_embedding_ops  # noqa: F401  # noqa: F401
diff --git a/fbgemm_gpu/fbgemm_gpu/docs/common.py b/fbgemm_gpu/fbgemm_gpu/docs/common.py
@@ -0,0 +1,9 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+
+def add_docs(method, docstr: str):
+    method.__doc__ = docstr