pytorch · d4l3k · Mar 1, 2022
diff --git a/.github/workflows/doc-build.yaml b/.github/workflows/doc-build.yaml
@@ -42,6 +42,17 @@ jobs:
         run: |
           cd docs
           make papermill
+      - name: Coverage
+        run: |
+          set -ex
+          cd docs
+          make coverage
+          if [ "$(wc -l build/*/coverage/python.txt)" -ne 2 ]
+          then
+              cat build/*/coverage/python.txt
+              echo "missing documentation coverage!"
+              exit 1
+          fi
 
   docpush:
     runs-on: ubuntu-18.04

diff --git a/docs/source/app_best_practices.rst b/docs/source/app_best_practices.rst
@@ -111,7 +111,7 @@ model definition from a python file and then you'll load the weights and state
 dict from a ``.ckpt`` or ``.pt`` file.
 
 This is how Pytorch Lightning's
-`ModelCheckpoint <https://pytorch-lightning.readthedocs.io/en/latest/extensions/generated/pytorch_lightning.callbacks.ModelCheckpoint.html>`__ hook works.
+`ModelCheckpoint <https://pytorch-lightning.readthedocs.io/en/latest/api/pytorch_lightning.callbacks.ModelCheckpoint.html>`__ hook works.
 
 This is the most common but makes it harder to make a reusable app since your
 trainer app needs to include the model definition code.

diff --git a/docs/source/basics.rst b/docs/source/basics.rst
@@ -10,11 +10,12 @@ The top level modules in TorchX are:
 
 1. :mod:`torchx.specs`: application spec (job definition) APIs
 2. :mod:`torchx.components`: predefined (builtin) app specs
-3. :mod:`torchx.runner`: given an app spec, submits the app as a job on a scheduler
-4. :mod:`torchx.schedulers`: backend job schedulers that the runner supports
-5. :mod:`torchx.pipelines`: adapters that convert the given app spec to a "stage" in an ML pipeline platform
-6. :mod:`torchx.runtime`: util and abstraction libraries you can use in authoring apps (not app spec)
-7. :mod:`torchx.cli`: CLI tool
+3. :mod:`torchx.workspace`: handles patching images for remote execution
+4. :mod:`torchx.cli`: CLI tool
+5. :mod:`torchx.runner`: given an app spec, submits the app as a job on a scheduler
+6. :mod:`torchx.schedulers`: backend job schedulers that the runner supports
+7. :mod:`torchx.pipelines`: adapters that convert the given app spec to a "stage" in an ML pipeline platform
+8. :mod:`torchx.runtime`: util and abstraction libraries you can use in authoring apps (not app spec)
 
 Below is a UML diagram
 

diff --git a/docs/source/components/utils.rst b/docs/source/components/utils.rst
@@ -4,9 +4,10 @@ Utils
 .. automodule:: torchx.components.utils
 .. currentmodule:: torchx.components.utils
 
-.. autofunction:: torchx.components.utils.echo
-.. autofunction:: torchx.components.utils.touch
-.. autofunction:: torchx.components.utils.sh
-.. autofunction:: torchx.components.utils.copy
-.. autofunction:: torchx.components.utils.python
-.. autofunction:: torchx.components.utils.booth
+.. autofunction:: echo
+.. autofunction:: touch
+.. autofunction:: sh
+.. autofunction:: copy
+.. autofunction:: python
+.. autofunction:: booth
+.. autofunction:: binary
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -66,6 +66,12 @@
     "IPython.sphinxext.ipython_console_highlighting",
 ]
 
+# coverage options
+
+coverage_ignore_modules = [
+    "torchx.components.component_test_base",
+]
+
 # katex options
 #
 #

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -16,7 +16,7 @@ most unique applications can be serviced without customizing the whole vertical
 
 
 **GETTING STARTED?** First learn the :ref:`basic concepts<basics:Basic Concepts>` and
-follow the :ref:`quickstart guide<quickstart:Quickstart>`.
+follow the :ref:`quickstart guide<quickstart:Quickstart - Custom Components>`.
 
 .. image:: torchx_index_diag.png
 
@@ -47,8 +47,37 @@ Documentation
    quickstart.md
    cli
 
+   runner.config
+
    advanced
 
+
+Works With
+---------------
+
+.. _Schedulers:
+.. toctree::
+   :maxdepth: 1
+   :caption: Schedulers
+
+   schedulers/local
+   schedulers/docker
+   schedulers/kubernetes
+   schedulers/slurm
+   schedulers/ray
+   schedulers/aws_batch
+
+.. _Pipelines:
+.. toctree::
+   :maxdepth: 1
+   :caption: Pipelines
+
+   pipelines/kfp
+
+
+Examples
+------------
+
 .. toctree::
    :maxdepth: 1
    :caption: Examples
@@ -58,6 +87,7 @@ Documentation
    examples_pipelines/index
 
 
+
 Components Library
 ---------------------
 .. _Components:
@@ -85,28 +115,6 @@ Runtime Library
    runtime/tracking
 
 
-Works With
----------------
-
-.. _Schedulers:
-.. toctree::
-   :maxdepth: 1
-   :caption: Schedulers
-
-   schedulers/local
-   schedulers/kubernetes
-   schedulers/slurm
-   schedulers/ray
-   schedulers/aws_batch
-
-.. _Pipelines:
-.. toctree::
-   :maxdepth: 1
-   :caption: Pipelines
-
-   pipelines/kfp
-
-
 Reference
 -----------
 
@@ -118,6 +126,7 @@ Reference
    specs
    runner
    schedulers
+   workspace
    pipelines
 
 .. toctree::
@@ -126,15 +135,3 @@ Reference
 
    app_best_practices
    component_best_practices
-
-
-Experimental
----------------
-.. toctree::
-   :maxdepth: 1
-   :caption: Experimental Features
-
-   experimental/runner.config
-
-
-
diff --git a/docs/source/quickstart.md b/docs/source/quickstart.md
@@ -12,7 +12,7 @@ jupyter:
     name: python3
 ---
 
-# Quickstart
+# Quickstart - Custom Components
 
 This is a self contained guide on how to build a simple app and component spec
 and launch it via two different schedulers.

diff --git a/docs/source/experimental/runner.config.rst → docs/source/runner.config.rst b/docs/source/experimental/runner.config.rst → docs/source/runner.config.rst
@@ -1,4 +1,4 @@
-(beta) .torchxconfig file
+.torchxconfig
 -----------------------------
 
 .. automodule:: torchx.runner.config
@@ -10,3 +10,7 @@ Config API Functions
 .. autofunction:: apply
 .. autofunction:: load
 .. autofunction:: dump
+.. autofunction:: find_configs
+.. autofunction:: get_configs
+.. autofunction:: get_config
+.. autofunction:: load_sections
diff --git a/docs/source/runtime/hpo.rst b/docs/source/runtime/hpo.rst
@@ -14,4 +14,7 @@ Ax (Adaptive Experimentation)
 .. currentmodule:: torchx.runtime.hpo.ax
 
 .. autoclass:: TorchXRunner
+   :members:
+
 .. autoclass:: AppMetric
+   :members:
diff --git a/docs/source/schedulers/aws_batch.rst b/docs/source/schedulers/aws_batch.rst
@@ -2,7 +2,17 @@ AWS Batch
 =================
 
 .. automodule:: torchx.schedulers.aws_batch_scheduler
+
 .. currentmodule:: torchx.schedulers.aws_batch_scheduler
 
 .. autoclass:: AWSBatchScheduler
    :members:
+   :show-inheritance:
+
+.. autoclass:: BatchJob
+   :members:
+
+Reference
+~~~~~~~~~~~~
+
+.. autofunction:: create_scheduler
diff --git a/docs/source/schedulers/docker.rst b/docs/source/schedulers/docker.rst
@@ -0,0 +1,23 @@
+Docker
+=================
+
+.. automodule:: torchx.schedulers.docker_scheduler
+
+.. currentmodule:: torchx.schedulers.docker_scheduler
+
+.. autoclass:: DockerScheduler
+   :members:
+   :show-inheritance:
+
+.. autoclass:: DockerJob
+   :members:
+
+Reference
+~~~~~~~~~~~~
+
+.. autofunction:: create_scheduler
+
+.. autoclass:: DockerContainer
+   :members:
+
+.. autofunction:: has_docker
diff --git a/docs/source/schedulers/kubernetes.rst b/docs/source/schedulers/kubernetes.rst
@@ -2,8 +2,22 @@ Kubernetes
 =================
 
 .. automodule:: torchx.schedulers.kubernetes_scheduler
+
 .. currentmodule:: torchx.schedulers.kubernetes_scheduler
 
 .. autoclass:: KubernetesScheduler
    :members:
+   :show-inheritance:
+
+.. autoclass:: KubernetesJob
+   :members:
+
+Reference
+~~~~~~~~~~~~
 
+.. autofunction:: create_scheduler
+.. autofunction:: app_to_resource
+.. autofunction:: cleanup_str
+.. autofunction:: pod_labels
+.. autofunction:: role_to_pod
+.. autofunction:: sanitize_for_serialization
diff --git a/docs/source/schedulers/local.rst b/docs/source/schedulers/local.rst
@@ -2,24 +2,38 @@ Local
 =================
 
 .. automodule:: torchx.schedulers.local_scheduler
+
 .. currentmodule:: torchx.schedulers.local_scheduler
 
 .. autoclass:: LocalScheduler
    :members:
-
-.. automodule:: torchx.schedulers.docker_scheduler
-.. currentmodule:: torchx.schedulers.docker_scheduler
-
-.. autoclass:: DockerScheduler
-   :members:
+   :show-inheritance:
 
 Image Providers
 ~~~~~~~~~~~~~~~~~
 
-.. currentmodule:: torchx.schedulers.local_scheduler
-
 .. autoclass:: ImageProvider
    :members:
 
 .. autoclass:: CWDImageProvider
    :members:
+
+.. autoclass:: LocalDirectoryImageProvider
+   :members:
+
+Reference
+~~~~~~~~~~~~
+
+.. autofunction:: create_cwd_scheduler
+
+.. autoclass:: LogIterator
+   :members:
+
+.. autoclass:: PopenRequest
+   :members:
+
+.. autoclass:: ReplicaParam
+   :members:
+
+.. autoclass:: SignalException
+   :members:
diff --git a/docs/source/schedulers/ray.rst b/docs/source/schedulers/ray.rst
@@ -2,7 +2,16 @@ Ray
 =================
 
 .. automodule:: torchx.schedulers.ray_scheduler
+
 .. currentmodule:: torchx.schedulers.ray_scheduler
 
 .. autoclass:: RayScheduler
    :members:
+   :show-inheritance:
+
+.. autofunction:: create_scheduler
+.. autofunction:: has_ray
+.. autofunction:: serialize
+
+.. autoclass:: RayJob
+   :members:
diff --git a/docs/source/schedulers/slurm.rst b/docs/source/schedulers/slurm.rst
@@ -2,7 +2,17 @@ Slurm
 =================
 
 .. automodule:: torchx.schedulers.slurm_scheduler
+
 .. currentmodule:: torchx.schedulers.slurm_scheduler
 
 .. autoclass:: SlurmScheduler
    :members:
+   :show-inheritance:
+
+.. autofunction:: create_scheduler
+
+.. autoclass:: SlurmBatchRequest
+   :members:
+
+.. autoclass:: SlurmReplicaRequest
+   :members: