Reorganize docs, include README sections in docs (#40)

* Reorganize docs TOC

* Add README sections to the documentation

Author: gpleiss

README.md

@@ -8,6 +8,9 @@
 [![Conda](https://img.shields.io/conda/v/gpytorch/linear_operator.svg)](https://anaconda.org/gpytorch/linear_operator)
 [![PyPI](https://img.shields.io/pypi/v/linear_operator.svg)](https://pypi.org/project/linear_operator)
 
+
+<!-- docs_intro_start -->
+
 LinearOperator is a PyTorch package for abstracting away the linear algebra routines needed for structured matrices (or operators).
 
 **This package is in beta.**
@@ -21,6 +24,8 @@ Package development TODOs:
  - [ ] Add algebraic routines for generic rectangular operators
  - [ ] Add sparse operators
 
+<!-- docs_intro_end -->
+
 To get started, run either
 ```sh
 pip install linear_operator
@@ -29,6 +34,10 @@ conda install linear_operator -c gpytorch
 ```
 or [see below](#installation) for more detailed instructions.
 
+
+<!-- docs_index_start -->
+
+
 ## Why LinearOperator
 Before describing what linear operators are and why they make a useful abstraction, it's easiest to see an example.
 Let's say you wanted to compute a matrix solve:
@@ -122,7 +131,12 @@ A = LowRankRootLinearOperator(C) + DiagLinearOperator(d)  # represents a 10M x 1
 torch.linalg.solve(A, b)  # computes A^{-1} b efficiently!
 ```
 
-### What is a Linear Operator?
+
+<!-- docs_index_end -->
+<!-- docs_about_start -->
+
+
+## What is a Linear Operator?
 A linear operator is a generalization of a matrix.
 It is a linear function that is defined in by its application to a vector.
 The most common linear operators are (potentially structured) matrices,
@@ -170,7 +184,6 @@ torch.matmul(D, torch.tensor([4., 5., 6.])
 # Returns [4., 10., 18.]
 ```
 
-#### Why is This Useful?
 While `_matmul`, `_size`, and `_transpose_nonbatch` might seem like a limited set of functions,
 it turns out that most functions on the `torch` and `torch.linalg` namespaces can be efficiently implemented
 using only these three primitative functions.
@@ -181,8 +194,13 @@ This makes it possible to define very complex compositional structures that stil
 
 Finally, `LinearOperator` objects can be composed with one another, yielding new `LinearOperator` objects and automatically keeping track of algebraic structure after each computation.
 As a result, users never need to reason about what efficient linear algebra routines to use  (so long as the input elements defined by the user encode known input structure).
+<!-- docs_about_end -->
 See the [using LinearOperator objects](#using-linearoperator-objects) section for more details.
 
+
+<!-- docs_usecases_start -->
+
+
 ## Use Cases
 
 There are several use cases for the LinearOperator package.
@@ -236,6 +254,10 @@ torch.linalg.solve(A, torch.randn(20000))  # Sub O(N^3) routine!
 ```
 
 
+<!-- docs_usecases_end -->
+<!-- docs_using_start -->
+
+
 ## Using LinearOperator Objects
 
 LinearOperator objects share (mostly) the same API as `torch.Tensor` objects.
@@ -330,6 +352,11 @@ This includes:
 
 See the documentation for a [full list of supported composition and decoration operations](https://linear-operator.readthedocs.io/en/latest/composition_decoration_operators.html).
 
+
+<!-- docs_using_end -->
+<!-- docs_install_start -->
+
+
 ## Installation
 
 LinearOperator requires Python >= 3.8.
@@ -357,6 +384,10 @@ To install what is currently on the `main` branch (potentially buggy and unstabl
 pip install --upgrade git+https://github.com/cornellius-gp/linear_operator.git
 ```
 
+
+<!-- docs_install_end -->
+
+
 ### Development Installation
 If you are contributing a pull request, it is best to perform a manual installation:
 

docs/requirements.txt

@@ -1,3 +1,4 @@
+myst-parser
 setuptools_scm
 sphinx
 sphinx_rtd_theme

docs/source/about.rst

@@ -0,0 +1,7 @@
+.. role:: hidden
+    :class: hidden-section
+
+.. include:: ../../README.md
+   :start-after: <!-- docs_about_start -->
+   :end-before: <!-- docs_about_end -->
+   :parser: myst_parser.sphinx_

docs/source/conf.py

@@ -44,6 +44,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "myst_parser",  # For adding sections of the README to the docs
     "sphinx.ext.intersphinx",
     "sphinx.ext.coverage",
     "sphinx.ext.mathjax",
@@ -53,6 +54,12 @@
     "sphinx_autodoc_typehints",
 ]
 
+myst_enable_extensions = [
+    "amsmath",  # Ensure markdown math from README gets compiled into rst math
+    "dollarmath",  # Ensure markdown math from README gets compiled into rst math
+    "tasklist",  # Check boxes
+]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 

docs/source/converting.rst

@@ -4,11 +4,6 @@
 Converting Between LinearOperators and torch.Tensor
 ====================================================
 
-TODO
-
 .. autofunction:: linear_operator.to_linear_operator
 
 .. autofunction:: linear_operator.to_dense
-
-.. autoclass:: linear_operator.operators.DenseLinearOperator
-   :members:

docs/source/index.rst

@@ -5,25 +5,52 @@
 
 :github_url: https://github.com/cornellius-gp/linear_operator
 
-LinearOperator Documentation
+LinearOperator
 ===========================================
 
+.. include:: ../../README.md
+   :start-after: <!-- docs_intro_start -->
+   :end-before: <!-- docs_intro_end -->
+   :parser: myst_parser.sphinx_
+
+Why LinearOperator
+------------------
+
+.. include:: ../../README.md
+   :start-after: <!-- docs_index_start -->
+   :end-before: <!-- docs_index_end -->
+   :parser: myst_parser.sphinx_
+
+Use Cases
+----------
+
+.. include:: ../../README.md
+   :start-after: ## Use Cases
+   :end-before: ## Using LinearOperator Objects
+   :parser: myst_parser.sphinx_
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Getting Started
+
+   self
+   install
+
 .. toctree::
    :maxdepth: 1
    :caption: Basic Concepts
 
-   intro
+   about
+   using
    converting
-   structure
    custom_linear_operators
 
 
 .. toctree::
    :maxdepth: 1
    :caption: Core API
 
-   namespace
-   settings
 
 
 .. toctree::
@@ -33,12 +60,15 @@ LinearOperator Documentation
    linear_operator
    data_sparse_operators
    composition_decoration_operators
+   structure
 
 
 .. toctree::
    :maxdepth: 1
    :caption: Advanced Package Reference
 
+   settings
+   namespace
    utils
 
 

docs/source/install.rst

@@ -0,0 +1,7 @@
+.. role:: hidden
+    :class: hidden-section
+
+.. include:: ../../README.md
+   :start-after: <!-- docs_install_start -->
+   :end-before: <!-- docs_install_end -->
+   :parser: myst_parser.sphinx_

docs/source/intro.rst

@@ -4,6 +4,9 @@
 .. currentmodule:: linear_operator
 
 
+Functions
+==============================
+
 LinearOperator objects are designed to work seamlessly with the torch API.
 For example:
 
@@ -23,9 +26,6 @@ These functions are designed to work on :class:`~linear_operator.operators.Linea
 objects alike.
 
 
-linear_operator
-----------------
-
 .. automodule:: linear_operator
 
 .. autofunction:: add_diagonal

docs/source/namespace.rst

@@ -1,7 +1,7 @@
 .. role:: hidden
     :class: hidden-section
 
-linear_operator.settings
+Settings
 ===================================
 
 .. currentmodule:: linear_operator.settings