Add stable API doc (#3194)

Summary: X-link: facebookresearch/FBGEMM#290 As title Pull Request resolved: #3194 Reviewed By: shintaro-iwasaki Differential Revision: D63601834 Pulled By: sryap
pytorch · Oct 1, 2024 · 2bfd8fb · 2bfd8fb
1 parent 9655d8f
commit 2bfd8fb
Show file tree

Hide file tree

Showing 8 changed files with 95 additions and 3 deletions.
diff --git a/fbgemm_gpu/docs/src/fbgemm_gpu-python-api/jagged_tensor_ops.rst b/fbgemm_gpu/docs/src/fbgemm_gpu-python-api/jagged_tensor_ops.rst
@@ -3,14 +3,22 @@ Jagged Tensor Operators
 
 .. automodule:: fbgemm_gpu
 
+.. _jagged-tensor-ops-stable-api:
+
+Stable API
+----------
+
+.. autofunction:: torch.ops.fbgemm.jagged_to_padded_dense
+
+Other API
+---------
+
 .. 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

diff --git a/fbgemm_gpu/docs/src/fbgemm_gpu-python-api/pooled_embedding_modules.rst b/fbgemm_gpu/docs/src/fbgemm_gpu-python-api/pooled_embedding_modules.rst
@@ -3,5 +3,13 @@ Pooled Embedding Modules
 
 .. automodule:: fbgemm_gpu
 
+.. _pooled-embedding-modules-stable-api:
+
+Stable API
+----------
+
 .. autoclass:: fbgemm_gpu.permute_pooled_embedding_modules.PermutePooledEmbeddings
    :members: __call__
+
+Other API
+---------
diff --git a/fbgemm_gpu/docs/src/fbgemm_gpu-python-api/pooled_embedding_ops.rst b/fbgemm_gpu/docs/src/fbgemm_gpu-python-api/pooled_embedding_ops.rst
@@ -3,6 +3,14 @@ Pooled Embedding Operators
 
 .. automodule:: fbgemm_gpu
 
+.. _pooled-embedding-operators-stable-api:
+
+Stable API
+----------
+
 .. autofunction:: torch.ops.fbgemm.merge_pooled_embeddings
 
 .. autofunction:: torch.ops.fbgemm.permute_pooled_embs
+
+Other API
+---------
diff --git a/fbgemm_gpu/docs/src/fbgemm_gpu-python-api/quantize_ops.rst b/fbgemm_gpu/docs/src/fbgemm_gpu-python-api/quantize_ops.rst
@@ -3,4 +3,12 @@ Quantization Operators
 
 .. automodule:: fbgemm_gpu
 
+.. _quantize-ops-stable-api:
+
+Stable API
+----------
+
 .. autofunction:: torch.ops.fbgemm.FloatOrHalfToFusedNBitRowwiseQuantizedSBHalf
+
+Other API
+---------
diff --git a/fbgemm_gpu/docs/src/fbgemm_gpu-python-api/sparse_ops.rst b/fbgemm_gpu/docs/src/fbgemm_gpu-python-api/sparse_ops.rst
@@ -3,6 +3,11 @@ Sparse Operators
 
 .. automodule:: fbgemm_gpu
 
+.. _sparse-ops-stable-api:
+
+Stable API
+----------
+
 .. autofunction:: torch.ops.fbgemm.permute_2D_sparse_data
 
 .. autofunction:: torch.ops.fbgemm.permute_1D_sparse_data
@@ -17,4 +22,6 @@ Sparse Operators
 
 .. autofunction:: torch.ops.fbgemm.keyed_jagged_index_select_dim1
 
-.. autofunction:: torch.ops.fbgemm.block_bucketize_sparse_features
+.. autofunction:: torch.ops.fbgemm.block_bucketize_sparse_features
+
+Other API
diff --git a/fbgemm_gpu/docs/src/fbgemm_gpu-python-api/table_batched_embedding_ops.rst b/fbgemm_gpu/docs/src/fbgemm_gpu-python-api/table_batched_embedding_ops.rst
@@ -1,10 +1,18 @@
 Table Batched Embedding (TBE) Training Module
 =============================================
 
+.. _table-batched-embedding-ops-stable-api:
+
+Stable API
+----------
+
 .. autoclass:: fbgemm_gpu.split_table_batched_embeddings_ops_training.SplitTableBatchedEmbeddingBagsCodegen
     :members: forward,
               split_embedding_weights,
               split_optimizer_states,
               set_learning_rate,
               update_hyper_parameters,
               set_optimizer_step
+
+Other API
+---------
diff --git a/fbgemm_gpu/docs/src/fbgemm_gpu-stable-api/python_api.rst b/fbgemm_gpu/docs/src/fbgemm_gpu-stable-api/python_api.rst
@@ -0,0 +1,37 @@
+FBGEMM_GPU Stable Python API
+============================
+
+We provide the stable API support starting from FBGEMM_GPU v1.0. The following
+outlines our supports:
+
+- API backward compatibility guarantees via thorough testing. We guarantee that
+  our stable APIs will be backward compatible within a major version, meaning
+  that the stable APIs for v1.0.0 will be compatible with every future release
+  unless explicitly announced in advance
+
+- Enhanced documentation, ensuring that every stable API has comprehensive and
+  up-to-date documentation.
+
+- Functionality guarantees are only provided through unit testing framework.
+  We do NOT guarantee any functionalities that are NOT explicitly tested and
+  documented in our unit tests.
+
+- No performance guarantees. However, we are committed to providing support on
+  a best-effort basis.
+
+Stable APIs
+-----------
+
+Our stable APIs can be found via the links below:
+
+- :ref:`Table batched embedding (TBE) modules<table-batched-embedding-ops-stable-api>`
+
+- :ref:`Pooled embedding operators<pooled-embedding-operators-stable-api>`
+
+- :ref:`Pooled embedding modules<pooled-embedding-modules-stable-api>`
+
+- :ref:`Sparse operators<sparse-ops-stable-api>`
+
+- :ref:`Jagged tensor operators<jagged-tensor-ops-stable-api>`
+
+- :ref:`Quantization operators<quantize-ops-stable-api>`
diff --git a/fbgemm_gpu/docs/src/index.rst b/fbgemm_gpu/docs/src/index.rst
@@ -56,6 +56,14 @@ Table of Contents
 
    fbgemm_gpu-overview/jagged-tensor-ops/JaggedTensorOps.rst
 
+.. _fbgemm.toc.api.stable:
+
+.. toctree::
+   :maxdepth: 1
+   :caption: FBGEMM Stable API
+
+   fbgemm_gpu-stable-api/python_api.rst
+
 .. _fbgemm.toc.api.cpp:
 
 .. toctree::