From 18875fb760a133883704b51ee95a325de40c019a Mon Sep 17 00:00:00 2001
From: Andreas Kloeckner <inform@tiker.net>
Date: Wed, 26 Aug 2020 13:22:29 -0500
Subject: [PATCH 1/4] Run Gitlab CI doc job on all branches, not just master

---
 .gitlab-ci.yml | 2 --
 1 file changed, 2 deletions(-)

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index ea72e3a..0f9e7fa 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -69,5 +69,3 @@ Documentation:
   - ". ./build-docs.sh"
   tags:
   - python3
-  only:
-  - master
-- 
GitLab


From 09b34bce91a2d4a9a5f6df8a57c6bb957a917584 Mon Sep 17 00:00:00 2001
From: Andreas Kloeckner <inform@tiker.net>
Date: Wed, 26 Aug 2020 13:23:13 -0500
Subject: [PATCH 2/4] Initial doc reference fixes

---
 doc/conf.py       |  2 ++
 doc/design.rst    |  8 +++---
 doc/reference.rst |  2 ++
 pytato/array.py   | 70 +++++++++++++++++++++++++++++++++++++++++------
 pytato/codegen.py |  2 ++
 pytato/program.py |  8 +++---
 6 files changed, 75 insertions(+), 17 deletions(-)

diff --git a/doc/conf.py b/doc/conf.py
index 96130ca..3b217f6 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -34,6 +34,8 @@ extensions = [
     'sphinx_autodoc_typehints',
 ]
 
+autoclass_content = "class"
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
diff --git a/doc/design.rst b/doc/design.rst
index 5114de6..a569511 100644
--- a/doc/design.rst
+++ b/doc/design.rst
@@ -71,7 +71,7 @@ Naming
 -   There is (for now) one :class:`~Namespace` per computation "universe" that defines
     the computational "environment", by mapping :term:`identifier`\ s to :term:`array expression`\ s
     (note: :class:`DictOfNamedArrays` instances may not be named, but their constituent
-    parts can, by using :class:`AttributeLookup`).
+    parts can, by using :class:`pytato.array.AttributeLookup`).
     Operations involving array expressions not using the same namespace are prohibited.
 
 -   Names in the :class:`~Namespace` are under user control and unique. I.e.
@@ -95,7 +95,7 @@ Naming
 
         A[(A > 0).tagged(CountNamed("mycount"))]
 
--   :class:`Placeholder` expressions, like all array expressions,
+-   :class:`pytato.array.Placeholder` expressions, like all array expressions,
     are considered read-only. When computation begins, the same
     actual memory may be supplied for multiple :term:`placeholder name`\ s,
     i.e. those arrays may alias.
@@ -135,7 +135,7 @@ Reserved Identifiers
 
     -   Identifiers matching the regular expression ``_in[0-9]+``. They are used
         as automatically generated names (if required) in
-        :attr:`IndexLambda.bindings`.
+        :attr:`pytato.array.IndexLambda.bindings`.
 
 Glossary
 ========
@@ -158,6 +158,6 @@ Glossary
         in a :class:`Namespace`.
 
     placeholder name
-        See :attr:`Placeholder.name`.
+        See :attr:`pytato.array.Placeholder.name`.
 
 .. vim: shiftwidth=4
diff --git a/doc/reference.rst b/doc/reference.rst
index 581f7b6..5ee32af 100644
--- a/doc/reference.rst
+++ b/doc/reference.rst
@@ -1,6 +1,8 @@
 Reference
 =========
 
+.. module:: pytato
+
 .. automodule:: pytato.array
 .. automodule:: pytato.scalar_expr
 .. automodule:: pytato.transform
diff --git a/pytato/array.py b/pytato/array.py
index 42070f5..cf604d6 100644
--- a/pytato/array.py
+++ b/pytato/array.py
@@ -73,6 +73,7 @@ Pre-Defined Tags
 ----------------
 
 .. autoclass:: ImplementAs
+.. autoclass:: ImplementationStrategy
 .. autoclass:: CountNamed
 .. autoclass:: ImplStored
 .. autoclass:: ImplInlined
@@ -86,6 +87,7 @@ Built-in Expression Nodes
 .. autoclass:: MatrixProduct
 .. autoclass:: LoopyFunction
 .. autoclass:: Stack
+.. autoclass:: AttributeLookup
 
 Index Remapping
 ^^^^^^^^^^^^^^^
@@ -118,6 +120,32 @@ Node constructors such as :class:`Placeholder.__init__` and
 .. autofunction:: make_placeholder
 .. autofunction:: make_size_param
 .. autofunction:: make_data_wrapper
+
+Aliases
+-------
+
+(This section exists because Sphinx, our documentation tool, can't canonicalize
+type references.)
+
+.. class:: Namespace
+
+    Should be referenced as :class:`pytato.Namespace`.
+
+.. class:: DottedName
+
+    Should be referenced as :class:`pytato.DottedName`.
+
+.. class:: Tag
+
+    Should be referenced as :class:`pytato.Tag`.
+
+.. class:: Array
+
+    Should be referenced as :class:`pytato.Array`.
+
+.. class:: DictOfNamedArrays
+
+    Should be referenced as :class:`pytato.DictOfNamedArrays`.
 """
 
 # }}}
@@ -200,8 +228,8 @@ class Namespace(Mapping[str, "Array"]):
     r"""
     Represents a mapping from :term:`identifier` strings to
     :term:`array expression`\ s or *None*, where *None* indicates that the name
-    may not be used.  (:class:`Placeholder` instances register their names in
-    this way to avoid ambiguity.)
+    may not be used.  (:class:`pytato.array.Placeholder` instances register
+    their names in this way to avoid ambiguity.)
 
     .. attribute:: name_gen
     .. automethod:: __contains__
@@ -290,6 +318,8 @@ class Tag:
     of the form ``dotted.name(attr1=value1, attr2=value2)``.
     Positional arguments are not allowed.
 
+   .. automethod:: __repr__
+
    .. note::
 
        This mirrors the tagging scheme that :mod:`loopy`
@@ -419,7 +449,7 @@ class Array:
 
     .. attribute:: shape
 
-        Identifiers (:class:`pymbolic.Variable`) refer to names from
+        Identifiers (:class:`pymbolic.primitives.Variable`) refer to names from
         :attr:`namespace`.  A tuple of integers or :mod:`pymbolic` expressions.
         Shape may be (at most affinely) symbolic in these
         identifiers.
@@ -427,7 +457,8 @@ class Array:
         .. note::
 
             Affine-ness is mainly required by code generation for
-            :class:`IndexLambda`, but :class:`IndexLambda` is used to produce
+            :class:`~pytato.array.IndexLambda`, but
+            :class:`~pytato.array.IndexLambda` is used to produce
             references to named arrays. Since any array that needs to be
             referenced in this way needs to obey this restriction anyway,
             a decision was made to requir the same of *all* array expressions.
@@ -796,10 +827,11 @@ class DictOfNamedArrays(Mapping[str, Array]):
     to instances of :class:`Array`. May occur as a result
     type of array computations.
 
-    .. method:: __contains__
-    .. method:: __getitem__
-    .. method:: __iter__
-    .. method:: __len__
+    .. automethod:: __init__
+    .. automethod:: __contains__
+    .. automethod:: __getitem__
+    .. automethod:: __iter__
+    .. automethod:: __len__
 
     .. note::
 
@@ -833,6 +865,8 @@ class DictOfNamedArrays(Mapping[str, Array]):
 
 class IndexLambda(_SuppliedShapeAndDtypeMixin, Array):
     """
+    .. attribute:: namespace
+
     .. attribute:: expr
 
         A scalar-valued :mod:`pymbolic` expression such as
@@ -1021,13 +1055,25 @@ class Stack(Array):
 # }}}
 
 
+# {{{ attribute lookup
+
+class AttributeLookup(Array):
+    """An expression node to extract an array from a :class:`DictOfNamedArrays`.
+
+    .. warning::
+
+        Not yet implemented.
+    """
+    pass
+
+
 # {{{ index remapping
 
 class IndexRemappingBase(Array):
     """Base class for operations that remap the indices of an array.
 
     Note that index remappings can also be expressed via
-    :class:`~pytato.IndexLambda`.
+    :class:`~pytato.array.IndexLambda`.
 
     .. attribute:: array
 
@@ -1267,6 +1313,9 @@ class DataWrapper(InputArgumentBase):
 class Placeholder(_SuppliedShapeAndDtypeMixin, InputArgumentBase):
     r"""A named placeholder for an array whose concrete value is supplied by the
     user during evaluation.
+
+    .. attribute:: name
+    .. automethod:: __init__
     """
 
     _mapper_method = "map_placeholder"
@@ -1277,6 +1326,9 @@ class Placeholder(_SuppliedShapeAndDtypeMixin, InputArgumentBase):
             shape: ShapeType,
             dtype: np.dtype,
             tags: Optional[TagsType] = None):
+        """Should not be called directly. Use :func:`make_placeholder`
+        instead.
+        """
         super().__init__(shape=shape,
                 dtype=dtype,
                 namespace=namespace,
diff --git a/pytato/codegen.py b/pytato/codegen.py
index a55b669..67d3f6a 100644
--- a/pytato/codegen.py
+++ b/pytato/codegen.py
@@ -78,6 +78,8 @@ Code Generation Internals
 .. autofunction:: rename_reductions
 .. autofunction:: normalize_outputs
 .. autofunction:: get_initial_codegen_state
+
+.. autoclass:: PreprocessResult
 .. autofunction:: preprocess
 
 """
diff --git a/pytato/program.py b/pytato/program.py
index ded1909..e2e2c86 100644
--- a/pytato/program.py
+++ b/pytato/program.py
@@ -40,8 +40,8 @@ from typing import Any, Mapping, Optional
 if typing.TYPE_CHECKING:
     # Imports skipped for efficiency.  FIXME: Neither of these work as type
     # stubs are not present. Types are here only as documentation.
-    import pyopencl as cl
-    import loopy as lp
+    import pyopencl
+    import loopy
     # Imports skipped to avoid circular dependencies.
     import pytato.target
 
@@ -65,7 +65,7 @@ class BoundProgram:
     .. automethod:: __call__
     """
 
-    program: "lp.LoopKernel"
+    program: "loopy.LoopKernel"
     bound_arguments: Mapping[str, Any]
     target: "pytato.target.Target"
 
@@ -83,7 +83,7 @@ class BoundPyOpenCLProgram(BoundProgram):
 
     .. automethod:: __call__
     """
-    queue: Optional["cl.CommandQueue"]
+    queue: Optional["pyopencl.CommandQueue"]
 
     def __call__(self, *args: Any, **kwargs: Any) -> Any:
         """Convenience function for launching a :mod:`pyopencl` computation."""
-- 
GitLab


From 6df440609de94c8f2b0329f9e3cb5c4c3395d441 Mon Sep 17 00:00:00 2001
From: Andreas Kloeckner <inform@tiker.net>
Date: Mon, 31 Aug 2020 19:31:45 -0500
Subject: [PATCH 3/4] More doc fixes

---
 .ci-support/fix-code-for-docs.sh |  2 ++
 .gitlab-ci.yml                   |  1 +
 doc/conf.py                      | 23 +++++++++++------------
 doc/misc.rst                     | 30 ++++++++++++++++++++++++++++++
 pytato/array.py                  |  7 ++++---
 pytato/codegen.py                | 12 +++++++++++-
 pytato/target.py                 | 19 +++++++------------
 7 files changed, 66 insertions(+), 28 deletions(-)
 create mode 100755 .ci-support/fix-code-for-docs.sh

diff --git a/.ci-support/fix-code-for-docs.sh b/.ci-support/fix-code-for-docs.sh
new file mode 100755
index 0000000..7d6da02
--- /dev/null
+++ b/.ci-support/fix-code-for-docs.sh
@@ -0,0 +1,2 @@
+#! /bin/bash
+sed -i "s/Dict\[str, DataInterface\]/Dict/" pytato/codegen.py
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 0f9e7fa..4255e09 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -66,6 +66,7 @@ Documentation:
   script:
   - EXTRA_INSTALL="sphinx-autodoc-typehints"
   - curl -L -O -k https://gitlab.tiker.net/inducer/ci-support/raw/master/build-docs.sh
+  - ./.ci-support/fix-code-for-docs.sh
   - ". ./build-docs.sh"
   tags:
   - python3
diff --git a/doc/conf.py b/doc/conf.py
index 3b217f6..5a61a6c 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -31,7 +31,6 @@ extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
     'sphinx.ext.mathjax',
-    'sphinx_autodoc_typehints',
 ]
 
 autoclass_content = "class"
@@ -57,15 +56,15 @@ html_theme = 'alabaster'
 html_static_path = []
 
 intersphinx_mapping = {
-    'http://docs.python.org/': None,
-    'http://documen.tician.de/boxtree/': None,
-    'http://docs.scipy.org/doc/numpy/': None,
-    'http://documen.tician.de/meshmode/': None,
-    'http://documen.tician.de/modepy/': None,
-    'http://documen.tician.de/pyopencl/': None,
-    'http://documen.tician.de/pytools/': None,
-    'http://documen.tician.de/pymbolic/': None,
-    'http://documen.tician.de/loopy/': None,
-    'http://documen.tician.de/sumpy/': None,
-    'http://documen.tician.de/islpy/': None,
+    'https://docs.python.org/3/': None,
+    'https://numpy.org/doc/stable/': None,
+    'https://documen.tician.de/boxtree/': None,
+    'https://documen.tician.de/meshmode/': None,
+    'https://documen.tician.de/modepy/': None,
+    'https://documen.tician.de/pyopencl/': None,
+    'https://documen.tician.de/pytools/': None,
+    'https://documen.tician.de/pymbolic/': None,
+    'https://documen.tician.de/loopy/': None,
+    'https://documen.tician.de/sumpy/': None,
+    'https://documen.tician.de/islpy/': None,
     }
diff --git a/doc/misc.rst b/doc/misc.rst
index c6ab970..5c6a7d0 100644
--- a/doc/misc.rst
+++ b/doc/misc.rst
@@ -26,3 +26,33 @@ WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 OTHER DEALINGS IN THE SOFTWARE.
 
+Cross-References for Other Documentation
+========================================
+.. class:: ellipsis
+
+    The type of the Python-builtin :data:`Ellipsis` object. (not otherwise
+    documented)
+
+.. currentmodule:: loopy.kernel
+
+.. class:: LoopKernel
+
+   See :class:`loopy.LoopKernel`.
+
+.. currentmodule:: loopy.options
+
+.. class:: Options
+
+   See :class:`loopy.Options`.
+
+.. currentmodule:: loopy.kernel.data
+
+.. class:: TemporaryVariable
+
+   See :class:`loopy.TemporaryVariable`.
+
+.. currentmodule:: islpy._isl
+
+.. class:: BasicSet
+
+   See :class:`islpy.BasicSet`.
diff --git a/pytato/array.py b/pytato/array.py
index cf604d6..be55c4e 100644
--- a/pytato/array.py
+++ b/pytato/array.py
@@ -110,7 +110,7 @@ User-Facing Node Creation
 -------------------------
 
 Node constructors such as :class:`Placeholder.__init__` and
-:class:`DictOfNamedArrays.__init__` offer limited input validation
+:class:`~pytato.DictOfNamedArrays.__init__` offer limited input validation
 (in favor of faster execution). Node creation from outside
 :mod:`pytato` should use the following interfaces:
 
@@ -124,8 +124,9 @@ Node constructors such as :class:`Placeholder.__init__` and
 Aliases
 -------
 
-(This section exists because Sphinx, our documentation tool, can't canonicalize
-type references.)
+(This section exists because Sphinx, our documentation tool, can't (yet)
+canonicalize type references. Once Sphinx 4.0 is released, we should use the
+``:canonical:`` option here.)
 
 .. class:: Namespace
 
diff --git a/pytato/codegen.py b/pytato/codegen.py
index 67d3f6a..496b176 100644
--- a/pytato/codegen.py
+++ b/pytato/codegen.py
@@ -47,6 +47,17 @@ from pytato.transform import Mapper, CopyMapper
 
 
 __doc__ = """
+References
+----------
+
+.. class:: DictOfNamedArrays
+
+    Should be referenced as :class:`pytato.DictOfNamedArrays`.
+
+.. class:: DataInterface
+
+    Should be referenced as :class:`pytato.array.DataInterface`.
+
 Generating Code
 ---------------
 
@@ -81,7 +92,6 @@ Code Generation Internals
 
 .. autoclass:: PreprocessResult
 .. autofunction:: preprocess
-
 """
 
 
diff --git a/pytato/target.py b/pytato/target.py
index 0242c0d..72e819b 100644
--- a/pytato/target.py
+++ b/pytato/target.py
@@ -32,17 +32,12 @@ Code Generation Targets
 .. autoclass:: PyOpenCLTarget
 """
 
-import typing
 from typing import Any, Mapping, Optional
 
 from pytato.program import BoundProgram, BoundPyOpenCLProgram
 
-
-if typing.TYPE_CHECKING:
-    # Skip imports for efficiency.  FIXME: Neither of these work as type stubs
-    # are not present. Types are here only as documentation.
-    import pyopencl as cl
-    import loopy as lp
+import pyopencl
+import loopy
 
 
 class Target:
@@ -52,11 +47,11 @@ class Target:
     .. automethod:: bind_program
     """
 
-    def get_loopy_target(self) -> "lp.TargetBase":
+    def get_loopy_target(self) -> "loopy.TargetBase":
         """Return the corresponding :mod:`loopy` target."""
         raise NotImplementedError
 
-    def bind_program(self, program: "lp.LoopKernel",
+    def bind_program(self, program: "loopy.LoopKernel",
             bound_arguments: Mapping[str, Any]) -> BoundProgram:
         """Create a :class:`pytato.program.BoundProgram` for this code generation target.
 
@@ -74,17 +69,17 @@ class PyOpenCLTarget(Target):
         The :mod:`pyopencl` command queue, or *None*.
     """
 
-    def __init__(self, queue: Optional["cl.CommandQueue"] = None):
+    def __init__(self, queue: Optional["pyopencl.CommandQueue"] = None):
         self.queue = queue
 
-    def get_loopy_target(self) -> "lp.PyOpenCLTarget":
+    def get_loopy_target(self) -> "loopy.PyOpenCLTarget":
         import loopy as lp
         device = None
         if self.queue is not None:
             device = self.queue.device
         return lp.PyOpenCLTarget(device)
 
-    def bind_program(self, program: "lp.LoopKernel",
+    def bind_program(self, program: "loopy.LoopKernel",
             bound_arguments: Mapping[str, Any]) -> BoundProgram:
         return BoundPyOpenCLProgram(program=program,
                 queue=self.queue,
-- 
GitLab


From 5716c6ee4c01aafb96f958896f5887478caaeea8 Mon Sep 17 00:00:00 2001
From: Andreas Kloeckner <inform@tiker.net>
Date: Mon, 31 Aug 2020 22:39:37 -0500
Subject: [PATCH 4/4] Install pyopencl for the Gitlab doc build

---
 .gitlab-ci.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 4255e09..cb8d11e 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -64,7 +64,7 @@ Mypy:
 
 Documentation:
   script:
-  - EXTRA_INSTALL="sphinx-autodoc-typehints"
+  - EXTRA_INSTALL="pyopencl"
   - curl -L -O -k https://gitlab.tiker.net/inducer/ci-support/raw/master/build-docs.sh
   - ./.ci-support/fix-code-for-docs.sh
   - ". ./build-docs.sh"
-- 
GitLab