Merge pull request #546 from nicolasvasilache/pr/cleanup-docs

Cleanup docs

Author: nicolasvasilache

docs/source/_static/img/autotuning-py.jpg

@@ -26,29 +26,7 @@ to express their operations and bridge the gap between research and engineering.
 Installation
 ------------
 
-We provide a :code:`conda` package for Tensor Comprehensions (only :code:`linux-64` package)
-to quickly get started with TC. Follow the steps below to install TC :code:`conda` package:
-
-**Step 1:** Setup Anaconda
-Make sure :code:`conda` bin is in your :code:`$PATH`. To verify, run the following command:
-
-.. code-block:: bash
-
-      $ which conda
-
-This command should print the path of your :code:`conda` bin. If it doesn't,
-please activate :code:`conda` (see `installation`_).
-
-**Step 2:** Install Tensor Comprehensions with Anaconda
-
-Now, go ahead and install Tensor Comprehensions by running following command.
-
-.. code-block:: bash
-
-      $ conda install -y -c pytorch -c tensorcomp tensor_comprehensions
-
-You are now ready to start using Tensor Comprehensions with PyTorch. As an example,
-let's see a simple example of writing :code:`matmul` layer with TC in PyTorch.
+See instructions here: :ref:`installation_guide`.
 
 Example
 -------

docs/source/framework/pytorch_integration/getting_started.rst

@@ -13,6 +13,32 @@ Comprehensions.
 
 .. autofunction:: make_autograd
 
+The :func:`define` function provides an implicit compilation caching
+functionality which alleviates the need to implement a caching mechanism at
+the user-facing level. The question still remains which :class:`~tclib.MappingOptions`
+to use to compile. Since this is still an open problem, we provide support
+for user-defined functions to specify this behavior. We require a user
+of the :func:`define` function to provide a :class:`~tclib.MappingOptions` generator
+function whose sole purpose is to determine the options with which to compile
+a particular TC def for particular input sizes.
+
+To facilitate usage we provide the following generators:
+		  
+.. autofunction:: make_naive_options_factory
+		  
+.. autofunction:: make_load_from_cache_options_factory
+		  
+.. autofunction:: make_autotuned_options_factory	 
+
+Custom behavior to select :class:`~tclib.MappingOptions` may be implemented
+in addition to the provided defaults. The signature of custom generators must
+match:
+
+.. code-block:: python
+		
+   def some_generator(tc: str, entry_point: str, *inputs: torch.Tensor)
+       -> MappingOptions:
+           ...
 
 Low-level API
 -------------
@@ -31,7 +57,7 @@ generally useful for benchmarking.
 
 .. autofunction:: autotune_and_compile
 
-Additionally the :code:`assert_almost_equal` helper function is useful in
+Additionally the :func:`assert_almost_equal` helper function is useful in
 performing numerical checks.
 
 .. autofunction:: assert_almost_equal

docs/source/framework/pytorch_integration/python_api.rst

@@ -1,17 +1,19 @@
 Writing TC operations
 =====================
 
+.. automodule:: tensor_comprehensions
+
 This document focuses on writing TC operations using the high-level API.
 For examples of using the low-level API, see the Python API documentation.
 
 To create a CUDA kernel implementing an operation backed by TC, one should:
 
 1. Create a callable TC object by calling :func:`define`
 2. Create input PyTorch Tensors
-3. Call the helper object with the input PyTorch Tensors
+3. Call the TC object with the input PyTorch Tensors
 
 When running, the backend ensures the TC is compiled and memoized for the
-given input tensor sizes (see the documentation for :func:`define` for more detals).
+given input tensor sizes (see the documentation for :func:`define` for more details).
 Calling the object returned by :func:`define` executes the
 corresponding operation and returns a list of outputs.
 If the operation has already been compiled, in the following runs, the TC
@@ -23,11 +25,11 @@ Example
 
 The following example demonstrates the steps above.
 We use the :func:`make_naive_options_factory` builder function to provide
-naive :class:`MappingOptions`.  Naive options result in poor performance.
-At this time, there is no notion of a default :class:`MappingOptions`.
+naive :class:`~tclib.MappingOptions`.  Naive options result in poor performance.
+At this time, there is no notion of a default :class:`~tclib.MappingOptions`.
 Instead one should use the autotuner to perform an evolutionary search
-starting from an initial :class:`MappingOptions` object and return a better
-:class:`MappingOptions` object for a given TC function and sizes (more on this
+starting from an initial :class:`~tclib.MappingOptions` object and return a better
+:class:`~tclib.MappingOptions` object for a given TC function and sizes (more on this
 below).
 
     .. code-block:: python
@@ -50,19 +52,19 @@ below).
 Specifying MappingOptions
 -------------------------
 
-There are three ways to construct :class:`MappingOptions` when defining a TC:
+There are three ways to construct :class:`~tclib.MappingOptions` when defining a TC:
 
 * **Naive MappingOptions**:
 
   * :code:`naive`: this is provided to create a basic GPU mapping strategy with
     3-D tiling by 32x32x32, mapping to 256x256 blocks 32x8 threads. This
     should by no means be considered a good baseline but just a point to
     get started using TC. Once a correct TC is written, we recommend either
-    using options loaded from a :class:`MappingOptionsCache` or resulting from
-    a tuning run. One can also modify a :class:`MappingOptions` object
+    using options loaded from a :class:`~tclib.MappingOptionsCache` or resulting from
+    a tuning run. One can also modify a :class:`~tclib.MappingOptions` object
     programmatically (see the API documentation).
 
-* **Loading from MappingOptionsCache**: a :class:`MappingOptionsCache` provides
+* **Loading from MappingOptionsCache**: a :class:`~tclib.MappingOptionsCache` provides
   a simple interface to load the best options from a previous tuning run.
 
 * **Autotuning**: A kernel can be autotuned for fixed input tensor sizes.
@@ -73,7 +75,7 @@ There are three ways to construct :class:`MappingOptions` when defining a TC:
 Loading from cache
 ------------------
 
-Loading the best options from a previously serialized :class:`MappingOptionsCache`
+Loading the best options from a previously serialized :class:`~tclib.MappingOptionsCache`
 can be achieved by making a factory function with
 :func:`make_load_from_cache_options_factory` and passing it as an argument to the
 :func:`define` function:
@@ -91,7 +93,7 @@ can be achieved by making a factory function with
             torch.randn(G, D, device='cuda'))
         Sum, SumSq, O = T.group_normalization(I, gamma, beta)
 
-One can also use the low-level :class:`MappingOptionsCache`.
+One can also use the low-level :class:`~tclib.MappingOptionsCache`.
 
 Autotuning
 ----------
@@ -121,10 +123,10 @@ Tuning can be achieved by making a factory function with
        that case, the compilation and evaluation jobs currently in flight will
        be flushed, but no new compilation job will be created. Once the jobs in
        flight are flushed, saving to cache occurs (if requested) and the best
-       :class:`MappingOptions` found so far will be returned.
+       :class:`~tclib.MappingOptions` found so far will be returned.
 
 Tuning behavior can be modified by defining the TC with an optional
-:class:`TunerConfig` parameter constructed as such:
+:class:`~tclib.TunerConfig` parameter constructed as such:
 :code:`tuner_config=tc.TunerConfig().threads(5).generations(3).pop_size(5)`.
 
     .. note::
@@ -198,6 +200,12 @@ functions. For example, assume one wants to use :code:`fmax` CUDA function in TC
         O = T.relu(torch.randn(100, 128, device='cuda'))
 
 TC only supports a subset of built-in CUDA functions.
-Built-in functions supported in TC are listed `here <https://github.com/facebookresearch/TensorComprehensions/blob/master/tc/core/libraries.h#L67>`_.
+Built-in functions supported in TC are listed in `this file <https://github.com/facebookresearch/TensorComprehensions/blob/master/tc/core/libraries.h#L67>`_.
 Documentation
-for these functions is available as part of the official CUDA documentation `here <http://docs.nvidia.com/cuda/cuda-math-api/group__CUDA__MATH__SINGLE.html#group__CUDA__MATH__SINGLE>`_.
+for these functions is available as part of the official `CUDA documentation <http://docs.nvidia.com/cuda/cuda-math-api/group__CUDA__MATH__SINGLE.html#group__CUDA__MATH__SINGLE>`_.
+
+
+More examples
+-------------
+You can find more examples in our `unit tests <https://github.com/facebookresearch/TensorComprehensions/blob/master/python/tests/test_tc.py>`_.
+We also provide more elaborate examples on how to `compute argmin <https://github.com/facebookresearch/TensorComprehensions/blob/master/python/examples/min_distance.py#L151>`_ as well as a simple TC + PyTorch `python overhead benchmark <https://github.com/facebookresearch/TensorComprehensions/blob/master/python/benchmarks/python_overhead.py>`_.

docs/source/framework/pytorch_integration/writing_layers.rst

@@ -60,9 +60,3 @@ Machine Learning.
    :caption: Support
 
    contacts
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Tutorials Reference
-
-   tutorials/index

docs/source/index.rst

@@ -1,3 +1,5 @@
+.. _installation_guide:
+
 Installation Guide
 ==================