Updates documentation pages and some doc strings. (pytorch#147)

Summary:
Pull Request resolved: pytorch#147

The PR updates the RST files to divide up some of the content currently in the different pages in docs. I also updated some docstrings to clear errors and warnings we're getting on the documentation build.

Please review this carefully as it does touch source files.

If you would prefer that I submit this as a diff, please still test this locally to make sure it's doing what you expect. (Then just message me and let me know.) You can test it by checking out this PR and building the docs:

cd docs
pip install -r requirements.txt
make html
cd build/html
python -m http.server
open https://localhost:8000 in browser.

Pull Request resolved: pytorch#140

Reviewed By: brianjo

Differential Revision: D34832340

Pulled By: colin2328

fbshipit-source-id: 9981bf58de3d74c29deb65f08c696ae49b909f8d

docs/.gitignore

@@ -0,0 +1 @@
+src/pytorch-sphinx-theme/

docs/source/conf.py

@@ -1,3 +1,10 @@
+#!/usr/bin/env python3
+# 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.
+
 # Configuration file for the Sphinx documentation builder.
 #
 # This file only contains a selection of the most common options. For a full
@@ -35,7 +42,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon"]
+extensions = ["sphinx.ext.napoleon", "sphinx.ext.autodoc"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

docs/source/index.rst

@@ -33,7 +33,10 @@ TorchRec API
    :caption: Contents:
 
    torchrec.datasets.rst
+   torchrec.datasets.scripts.rst
    torchrec.distributed.rst
+   torchrec.distributed.planner.rst
+   torchrec.distributed.sharding.rst
    torchrec.fx.rst
    torchrec.models.rst
    torchrec.modules.rst

docs/source/torchrec.datasets.rst

@@ -34,19 +34,3 @@ torchrec.datasets.utils
    :members:
    :undoc-members:
    :show-inheritance:
-
-torchrec.datasets.scripts.contiguous\_preproc\_criteo
---------------------------------------------
-
-.. automodule:: torchrec.datasets.scripts.contiguous_preproc_criteo
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-torchrec.datasets.scripts.npy\_preproc\_criteo
---------------------------------------------
-
-.. automodule:: torchrec.datasets.scripts.npy_preproc_criteo
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/source/torchrec.datasets.scripts.rst

@@ -0,0 +1,22 @@
+torchrec.datasets.scripts
+=========================
+
+.. automodule:: torchrec.datasets.scripts
+
+
+
+torchrec.datasets.scripts.contiguous\_preproc\_criteo
+-----------------------------------------------------
+
+.. automodule:: torchrec.datasets.scripts.contiguous_preproc_criteo
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+torchrec.datasets.scripts.npy\_preproc\_criteo
+----------------------------------------------
+
+.. automodule:: torchrec.datasets.scripts.npy_preproc_criteo
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/torchrec.distributed.planner.rst

@@ -0,0 +1,93 @@
+torchrec.distributed.planner
+============================
+
+.. automodule:: torchrec.distributed.planner
+
+
+torchrec.distributed.planner.constants
+--------------------------------------
+
+.. automodule:: torchrec.distributed.planner.constants
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+torchrec.distributed.planner.enumerators
+----------------------------------------
+
+.. automodule:: torchrec.distributed.planner.enumerators
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+torchrec.distributed.planner.partitioners
+-----------------------------------------
+
+.. automodule:: torchrec.distributed.planner.partitioners
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+torchrec.distributed.planner.perf\_models
+-----------------------------------------
+
+.. automodule:: torchrec.distributed.planner.perf_models
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+torchrec.distributed.planner.planners
+-------------------------------------
+
+.. automodule:: torchrec.distributed.planner.planners
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+torchrec.distributed.planner.proposers
+--------------------------------------
+
+.. automodule:: torchrec.distributed.planner.proposers
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+torchrec.distributed.planner.shard\_estimators
+----------------------------------------------
+
+.. automodule:: torchrec.distributed.planner.shard_estimators
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+torchrec.distributed.planner.stats
+----------------------------------
+
+.. automodule:: torchrec.distributed.planner.stats
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+torchrec.distributed.planner.storage\_reservations
+--------------------------------------------------
+
+.. automodule:: torchrec.distributed.planner.storage_reservations
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+torchrec.distributed.planner.types
+----------------------------------
+
+.. automodule:: torchrec.distributed.planner.types
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+torchrec.distributed.planner.utils
+----------------------------------
+
+.. automodule:: torchrec.distributed.planner.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/torchrec.distributed.rst

@@ -28,13 +28,6 @@ torchrec.distributed.comm\_ops
    :undoc-members:
    :show-inheritance:
 
-torchrec.distributed.sharding.cw\_sharding
----------------------------------
-
-.. automodule:: torchrec.distributed.sharding.cw_sharding
-   :members:
-   :undoc-members:
-   :show-inheritance:
 
 torchrec.distributed.dist\_data
 -------------------------------
@@ -44,14 +37,6 @@ torchrec.distributed.dist\_data
    :undoc-members:
    :show-inheritance:
 
-torchrec.distributed.sharding.dp\_sharding
----------------------------------
-
-.. automodule:: torchrec.distributed.sharding.sharding.dp_sharding
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 torchrec.distributed.embedding
 ------------------------------
 
@@ -116,14 +101,6 @@ torchrec.distributed.quant\_embeddingbag
    :undoc-members:
    :show-inheritance:
 
-torchrec.distributed.sharding.rw\_sharding
----------------------------------
-
-.. automodule:: torchrec.distributed.sharding.rw_sharding
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 torchrec.distributed.train\_pipeline
 ------------------------------------
 
@@ -132,30 +109,6 @@ torchrec.distributed.train\_pipeline
    :undoc-members:
    :show-inheritance:
 
-torchrec.distributed.sharding.tw\_sharding
----------------------------------
-
-.. automodule:: torchrec.distributed.sharding.tw_sharding
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-torchrec.distributed.sharding.twcw\_sharding
------------------------------------
-
-.. automodule:: torchrec.distributed.sharding.twcw_sharding
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-torchrec.distributed.sharding.twrw\_sharding
------------------------------------
-
-.. automodule:: torchrec.distributed.sharding.twrw_sharding
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 torchrec.distributed.types
 --------------------------
 
@@ -171,92 +124,3 @@ torchrec.distributed.utils
    :members:
    :undoc-members:
    :show-inheritance:
-
-
-torchrec.distributed.planner.constants
---------------------------------------
-
-.. automodule:: torchrec.distributed.planner.constants
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-torchrec.distributed.planner.enumerators
-----------------------------------------
-
-.. automodule:: torchrec.distributed.planner.enumerators
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-torchrec.distributed.planner.partitioners
------------------------------------------
-
-.. automodule:: torchrec.distributed.planner.partitioners
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-torchrec.distributed.planner.perf\_models
------------------------------------------
-
-.. automodule:: torchrec.distributed.planner.perf_models
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-torchrec.distributed.planner.planners
--------------------------------------
-
-.. automodule:: torchrec.distributed.planner.planners
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-torchrec.distributed.planner.proposers
---------------------------------------
-
-.. automodule:: torchrec.distributed.planner.proposers
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-torchrec.distributed.planner.shard\_estimators
-----------------------------------------------
-
-.. automodule:: torchrec.distributed.planner.shard_estimators
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-torchrec.distributed.planner.stats
-----------------------------------
-
-.. automodule:: torchrec.distributed.planner.stats
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-torchrec.distributed.planner.storage\_reservations
---------------------------------------------------
-
-.. automodule:: torchrec.distributed.planner.storage_reservations
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-torchrec.distributed.planner.types
-----------------------------------
-
-.. automodule:: torchrec.distributed.planner.types
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-torchrec.distributed.planner.utils
-----------------------------------
-
-.. automodule:: torchrec.distributed.planner.utils
-   :members:
-   :undoc-members:
-   :show-inheritance: