Merge pull request #293 from eric-wieser/tweak-docs

Manually tailor the class documentation pages
pygae · Apr 2, 2020 · 93b0188 · 93b0188
2 parents 3c70a07 + 8ae7ec7
commit 93b0188
Show file tree

Hide file tree

Showing 29 changed files with 121 additions and 43 deletions.
diff --git a/.gitignore b/.gitignore
@@ -60,3 +60,5 @@ target/
 
 .mypy_cache
 .ipynb_checkpoints
+
+/docs/api/generated/*
diff --git a/clifford/__init__.py b/clifford/__init__.py
@@ -14,15 +14,15 @@
 Note that typically the :doc:`predefined-algebras` are sufficient, and there is no need to build an algebra from scratch.
 
 .. autosummary::
-    :toctree: generated/
+    :toctree:
 
     Cl
     conformalize
 
 Whether you construct your algebras from scratch, or use the predefined ones, you'll end up working with the following types:
 
 .. autosummary::
-    :toctree: generated/
+    :toctree:
 
     MultiVector
     Layout
@@ -43,28 +43,30 @@
 ==============================
 These functions are used to change the global behavior of ``clifford``.
 
-.. autosummary::
-    :toctree: generated/
+.. autofunction:: eps
+
+.. autofunction:: pretty
+
+.. autofunction:: ugly
+
+.. autofunction:: print_precision
 
-    eps
-    pretty
-    ugly
-    print_precision
 
 Miscellaneous classes
 =======================
 
 .. autosummary::
-    :toctree: generated/
+    :toctree:
 
+    MVArray
     Frame
     BladeMap
 
 Miscellaneous functions
 =======================
 
 .. autosummary::
-    :toctree: generated/
+    :toctree:
 
     grade_obj
     randomMV

diff --git a/clifford/_blademap.py b/clifford/_blademap.py
@@ -1,7 +1,3 @@
-from . import _utils
-
-
-@_utils.set_module('clifford')
 class BladeMap(object):
     '''
     A Map Relating Blades in two different algebras

diff --git a/clifford/_conformal_layout.py b/clifford/_conformal_layout.py
@@ -2,10 +2,8 @@
 
 from ._layout import Layout
 from ._multivector import MultiVector
-from . import _utils
 
 
-@_utils.set_module('clifford')
 class ConformalLayout(Layout):
     r"""
     A layout for a conformal algebra, which adds extra constants and helpers.

diff --git a/clifford/_frame.py b/clifford/_frame.py
@@ -4,13 +4,11 @@
 import numpy as np
 
 from ._mvarray import MVArray
+from ._multivector import MultiVector
 from .operator import op
 from . import _settings
-from . import _utils
-from ._multivector import MultiVector
 
 
-@_utils.set_module('clifford')
 class Frame(MVArray):
     '''
     A frame of vectors

diff --git a/clifford/_layout.py b/clifford/_layout.py
@@ -18,7 +18,6 @@
 from . import _numba_utils
 from .io import read_ga_file
 from . import _settings
-from . import _utils
 from ._multivector import MultiVector
 from ._layout_helpers import (
     BasisBladeOrder, BasisVectorIds, canonical_reordering_sign_euclidean
@@ -176,7 +175,6 @@ def construct_graded_mt(
     return sparse.COO(coords=coords, data=mult_table_vals, shape=(dims, dims, dims))
 
 
-@_utils.set_module('clifford')
 class Layout(object):
     r""" Layout stores information regarding the geometric algebra itself and the
     internal representation of multivectors.

diff --git a/clifford/_layout_helpers.py b/clifford/_layout_helpers.py
@@ -14,7 +14,6 @@
 import operator
 
 from . import _numba_utils
-from . import _utils
 import numba
 import numba.extending
 import numba.types
@@ -73,7 +72,6 @@ def _is_unique(x) -> bool:
     return len(x) == len(set(x))
 
 
-@_utils.set_module('clifford')
 class BasisBladeOrder:
     """ Represents the storage order in memory of basis blade coefficients.
 
@@ -172,7 +170,6 @@ def __reduce__(self):
 IdT = TypeVar('IdT')
 
 
-@_utils.set_module('clifford')
 class BasisVectorIds(Generic[IdT]):
     """
     Stores ids for the ordered set of basis vectors, typically integers.

diff --git a/clifford/_multivector.py b/clifford/_multivector.py
@@ -7,10 +7,8 @@
 import clifford as cf
 from . import general_exp
 from . import _settings
-from . import _utils
 
 
-@_utils.set_module('clifford')
 class MultiVector(object):
     """An element of the algebra
 

diff --git a/clifford/_mvarray.py b/clifford/_mvarray.py
@@ -3,14 +3,12 @@
 
 from clifford.io import write_ga_file, read_ga_file  # noqa: F401
 from ._multivector import MultiVector
-from . import _utils
 
 dual_array = np.vectorize(MultiVector.dual)
 normal_array = np.vectorize(MultiVector.normal)
 call_array = np.vectorize(MultiVector.__call__)
 
 
-@_utils.set_module('clifford')
 class MVArray(np.ndarray):
     '''
     MultiVector Array

diff --git a/clifford/_utils.py b/clifford/_utils.py
diff --git a/docs/cga.rst → docs/api/cga.rst b/docs/cga.rst → docs/api/cga.rst
diff --git a/docs/api/clifford.BasisBladeOrder.rst b/docs/api/clifford.BasisBladeOrder.rst
@@ -0,0 +1,9 @@
+clifford.BasisBladeOrder
+========================
+
+.. currentmodule:: clifford
+
+.. autoclass:: BasisBladeOrder
+  :members:
+  :undoc-members:
+  :member-order: bysource
diff --git a/docs/api/clifford.BasisVectorIds.rst b/docs/api/clifford.BasisVectorIds.rst
@@ -0,0 +1,9 @@
+clifford.BasisVectorIds
+========================
+
+.. currentmodule:: clifford
+
+.. autoclass:: BasisVectorIds
+  :members:
+  :undoc-members:
+  :member-order: bysource
diff --git a/docs/api/clifford.BladeMap.rst b/docs/api/clifford.BladeMap.rst
@@ -0,0 +1,9 @@
+clifford.BladeMap
+=================
+
+.. currentmodule:: clifford
+
+.. autoclass:: BladeMap
+  :members:
+  :undoc-members:
+  :member-order: bysource
diff --git a/docs/api/clifford.Cl.rst b/docs/api/clifford.Cl.rst
@@ -0,0 +1,6 @@
+clifford.Cl
+===========
+
+.. currentmodule:: clifford
+
+.. autofunction:: Cl
diff --git a/docs/api/clifford.ConformalLayout.rst b/docs/api/clifford.ConformalLayout.rst
@@ -0,0 +1,10 @@
+clifford.ConformalLayout
+========================
+
+.. currentmodule:: clifford
+
+.. autoclass:: ConformalLayout
+  :members:
+  :undoc-members:
+  :show-inheritance:
+  :member-order: bysource
diff --git a/docs/api/clifford.Frame.rst b/docs/api/clifford.Frame.rst
@@ -0,0 +1,11 @@
+clifford.Frame
+==============
+
+.. currentmodule:: clifford
+
+.. autoclass:: Frame
+  :members:
+  :undoc-members:
+  :no-inherited-members:
+  :show-inheritance:
+  :member-order: bysource
diff --git a/docs/api/clifford.Layout.rst b/docs/api/clifford.Layout.rst
@@ -0,0 +1,9 @@
+clifford.Layout
+===============
+
+.. currentmodule:: clifford
+
+.. autoclass:: Layout
+  :members:
+  :member-order: bysource
+  :undoc-members:
diff --git a/docs/api/clifford.MVarray.rst b/docs/api/clifford.MVarray.rst
@@ -0,0 +1,11 @@
+clifford.MVArray
+================
+
+.. currentmodule:: clifford
+
+.. autoclass:: MVArray
+  :members:
+  :undoc-members:
+  :special-members: __call__
+  :no-inherited-members:
+  :show-inheritance:
diff --git a/docs/api/clifford.MultiVector.rst b/docs/api/clifford.MultiVector.rst
@@ -0,0 +1,11 @@
+clifford.MultiVector
+====================
+
+.. currentmodule:: clifford
+
+.. autoclass:: MultiVector
+  :no-inherited-members:
+  :members:
+  :undoc-members:
+  :special-members: __add__, __sub__, __mul__, __xor__, __or__, __invert__, __and__, __getitem__, __call__
+  :member-order: bysource
diff --git a/docs/api/clifford.conformalize.rst b/docs/api/clifford.conformalize.rst
@@ -0,0 +1,6 @@
+clifford.conformalize
+=====================
+
+.. currentmodule:: clifford
+
+.. autofunction:: conformalize
diff --git a/docs/api/clifford.grade_obj.rst b/docs/api/clifford.grade_obj.rst
@@ -0,0 +1,6 @@
+clifford.grade\_obj
+===================
+
+.. currentmodule:: clifford
+
+.. autofunction:: grade_obj
diff --git a/docs/api/clifford.randomMV.rst b/docs/api/clifford.randomMV.rst
@@ -0,0 +1,6 @@
+clifford.randomMV
+=================
+
+.. currentmodule:: clifford
+
+.. autofunction:: randomMV
diff --git a/docs/clifford.rst → docs/api/clifford.rst b/docs/clifford.rst → docs/api/clifford.rst
diff --git a/docs/api.rst → docs/api/index.rst b/docs/api.rst → docs/api/index.rst
diff --git a/docs/operator.rst → docs/api/operator.rst b/docs/operator.rst → docs/api/operator.rst
diff --git a/docs/tools.rst → docs/api/tools.rst b/docs/tools.rst → docs/api/tools.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -117,7 +117,8 @@
 #autodoc_default_flags='members'
 # you have to list all files with automodule here due to bug in sphinx and nbsphinx
 # https://github.com/spatialaudio/nbsphinx/issues/14
-autosummary_generate=['clifford','tools','cga']
+autosummary_generate=['api/tools', 'api/cga']
+autodoc_member_order = 'bysource'
 numpydoc_show_class_members = True
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

diff --git a/docs/index.rst b/docs/index.rst
@@ -34,7 +34,7 @@ Scalars, vectors, and higher-grade entities can be mixed freely and consistently
     :hidden:
 
     Installation
-    api
+    api/index
     predefined-algebras
     changelog
     issues