From ad04892ce6e3ebf0cbebf7c155b8f6d471a43ab4 Mon Sep 17 00:00:00 2001 From: Andreas Kloeckner Date: Tue, 18 Feb 2014 09:17:42 -0600 Subject: [PATCH] Move documentation into docstrings --- doc/mappers.rst | 60 -------------- doc/primitives.rst | 143 -------------------------------- pymbolic/mapper/__init__.py | 50 ++++++++++- pymbolic/mapper/stringifier.py | 21 +++++ pymbolic/primitives.py | 147 ++++++++++++++++++++++++++++++++- 5 files changed, 216 insertions(+), 205 deletions(-) diff --git a/doc/mappers.rst b/doc/mappers.rst index 11a0ef2..1c72dd0 100644 --- a/doc/mappers.rst +++ b/doc/mappers.rst @@ -3,51 +3,6 @@ Mappers .. automodule:: pymbolic.mapper -Basic dispatch --------------- - -.. autoclass:: Mapper - - .. automethod:: __call__ - - .. method:: rec(expr, *args, **kwargs) - - Identical to :meth:`__call__`, but intended for use in recursive dispatch - in mapper methods. - - .. automethod:: handle_unsupported_expression - - .. rubric:: Handling objects that don't declare mapper methods - - In particular, this includes many non-subclasses of - :class:`pymbolic.primitives.Expression`. - - .. automethod:: map_foreign - - These are abstract methods for foreign objects that should be overridden - in subclasses: - - .. method:: map_constant(expr, *args, **kwargs) - - Mapper method for constants. - See :func:`pymbolic.primitives.register_constant_class`. - - .. method:: map_list(expr, *args, **kwargs) - - .. method:: map_tuple(expr, *args, **kwargs) - - .. method:: map_numpy_array(expr, *args, **kwargs) - -Base classes for new mappers ----------------------------- - -.. autoclass:: CombineMapper - -.. autoclass:: IdentityMapper - -.. autoclass:: WalkMapper - -.. autoclass:: CSECachingMapperMixin More specialized mappers ------------------------ @@ -57,21 +12,6 @@ Converting to strings and code .. automodule:: pymbolic.mapper.stringifier -.. _prec-constants: - -Precedence constants -******************** - -.. data:: PREC_CALL -.. data:: PREC_POWER -.. data:: PREC_UNARY -.. data:: PREC_PRODUCT -.. data:: PREC_SUM -.. data:: PREC_COMPARISON -.. data:: PREC_LOGICAL_AND -.. data:: PREC_LOGICAL_OR -.. data:: PREC_NONE - Mappers ******* diff --git a/doc/primitives.rst b/doc/primitives.rst index a560a46..aa6eb62 100644 --- a/doc/primitives.rst +++ b/doc/primitives.rst @@ -3,147 +3,4 @@ Primitives (Basic Objects) .. automodule:: pymbolic.primitives -Expression base class ---------------------- - -.. autoclass:: Expression - - .. attribute:: attr - - .. attribute:: mapper_method - - The :class:`pymbolic.mapper.Mapper` method called for objects of - this type. - - .. automethod:: stringifier - - .. automethod:: __eq__ - .. automethod:: __hash__ - .. automethod:: __str__ - .. automethod:: __repr__ - -Sums, products and such ------------------------ - -.. autoclass:: Variable - :undoc-members: - :members: mapper_method - -.. autoclass:: Call - :undoc-members: - :members: mapper_method - -.. autoclass:: Subscript - :undoc-members: - :members: mapper_method - -.. autoclass:: Lookup - :undoc-members: - :members: mapper_method - -.. autoclass:: Sum - :undoc-members: - :members: mapper_method - -.. autoclass:: Product - :undoc-members: - :members: mapper_method - -.. autoclass:: Quotient - :undoc-members: - :members: mapper_method - -.. autoclass:: FloorDiv - :undoc-members: - :members: mapper_method - -.. autoclass:: Remainder - :undoc-members: - :members: mapper_method - -.. autoclass:: Power - :undoc-members: - :members: mapper_method - -Shift operators ---------------- - -.. autoclass:: LeftShift - :undoc-members: - :members: mapper_method - -.. autoclass:: RightShift - :undoc-members: - :members: mapper_method - -Bitwise operators ------------------ - -.. autoclass:: BitwiseNot - :undoc-members: - :members: mapper_method - -.. autoclass:: BitwiseOr - :undoc-members: - :members: mapper_method - -.. autoclass:: BitwiseXor - :undoc-members: - :members: mapper_method - -.. autoclass:: BitwiseAnd - :undoc-members: - :members: mapper_method - -Comparisons and logic ---------------------- - -.. autoclass:: Comparison - :undoc-members: - :members: mapper_method - -.. autoclass:: LogicalNot - :undoc-members: - :members: mapper_method - -.. autoclass:: LogicalAnd - :undoc-members: - :members: mapper_method - -.. autoclass:: LogicalOr - :undoc-members: - :members: mapper_method - -.. autoclass:: If - :undoc-members: - :members: mapper_method - -Code generation helpers ------------------------ - -.. autoclass:: CommonSubexpression - :undoc-members: - :members: mapper_method - -.. autoclass:: cse_scope -.. autofunction:: make_common_subexpression - -Helper functions ----------------- - -.. autofunction:: is_zero -.. autofunction:: is_constant -.. autofunction:: register_constant_class -.. autofunction:: unregister_constant_class -.. autofunction:: variables - -Interaction with :mod:`numpy` arrays ------------------------------------- - -:mod:`numpy.ndarray` instances are supported anywhere in an expression. -In particular, :mod:`numpy` object arrays are useful for capturing -vectors and matrices of :mod:`pymbolic` objects. - -.. autofunction:: make_sym_vector - .. vim: sw=4 diff --git a/pymbolic/mapper/__init__.py b/pymbolic/mapper/__init__.py index aa8f3e6..58da591 100644 --- a/pymbolic/mapper/__init__.py +++ b/pymbolic/mapper/__init__.py @@ -24,6 +24,54 @@ THE SOFTWARE. import pymbolic.primitives as primitives +__doc__ = """ +Basic dispatch +-------------- + +.. autoclass:: Mapper + + .. automethod:: __call__ + + .. method:: rec(expr, *args, **kwargs) + + Identical to :meth:`__call__`, but intended for use in recursive dispatch + in mapper methods. + + .. automethod:: handle_unsupported_expression + + .. rubric:: Handling objects that don't declare mapper methods + + In particular, this includes many non-subclasses of + :class:`pymbolic.primitives.Expression`. + + .. automethod:: map_foreign + + These are abstract methods for foreign objects that should be overridden + in subclasses: + + .. method:: map_constant(expr, *args, **kwargs) + + Mapper method for constants. + See :func:`pymbolic.primitives.register_constant_class`. + + .. method:: map_list(expr, *args, **kwargs) + + .. method:: map_tuple(expr, *args, **kwargs) + + .. method:: map_numpy_array(expr, *args, **kwargs) + +Base classes for new mappers +---------------------------- + +.. autoclass:: CombineMapper + +.. autoclass:: IdentityMapper + +.. autoclass:: WalkMapper + +.. autoclass:: CSECachingMapperMixin +""" + try: import numpy @@ -117,7 +165,7 @@ class Mapper(object): else: raise ValueError( "%s encountered invalid foreign object: %s" % ( - self.__class__, repr(expr))) + self.__class__, repr(expr))) # }}} diff --git a/pymbolic/mapper/stringifier.py b/pymbolic/mapper/stringifier.py index 19c11c9..c379c04 100644 --- a/pymbolic/mapper/stringifier.py +++ b/pymbolic/mapper/stringifier.py @@ -24,6 +24,27 @@ THE SOFTWARE. import pymbolic.mapper +__doc__ = """ +.. _prec-constants: + +Precedence constants +******************** + +.. data:: PREC_CALL +.. data:: PREC_POWER +.. data:: PREC_UNARY +.. data:: PREC_PRODUCT +.. data:: PREC_SUM +.. data:: PREC_SHIFT +.. data:: PREC_BITWISE_AND +.. data:: PREC_BITWISE_XOR +.. data:: PREC_BITWISE_OR +.. data:: PREC_COMPARISON +.. data:: PREC_LOGICAL_AND +.. data:: PREC_LOGICAL_OR +.. data:: PREC_NONE +""" + PREC_CALL = 15 PREC_POWER = 14 diff --git a/pymbolic/primitives.py b/pymbolic/primitives.py index f02bc98..829c702 100644 --- a/pymbolic/primitives.py +++ b/pymbolic/primitives.py @@ -22,7 +22,152 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. """ -import traits +import pymbolic.traits as traits + +__doc__ = """ +Expression base class +--------------------- + +.. autoclass:: Expression + + .. attribute:: attr + + .. attribute:: mapper_method + + The :class:`pymbolic.mapper.Mapper` method called for objects of + this type. + + .. automethod:: stringifier + + .. automethod:: __eq__ + .. automethod:: __hash__ + .. automethod:: __str__ + .. automethod:: __repr__ + +Sums, products and such +----------------------- + +.. autoclass:: Variable + :undoc-members: + :members: mapper_method + +.. autoclass:: Call + :undoc-members: + :members: mapper_method + +.. autoclass:: Subscript + :undoc-members: + :members: mapper_method + +.. autoclass:: Lookup + :undoc-members: + :members: mapper_method + +.. autoclass:: Sum + :undoc-members: + :members: mapper_method + +.. autoclass:: Product + :undoc-members: + :members: mapper_method + +.. autoclass:: Quotient + :undoc-members: + :members: mapper_method + +.. autoclass:: FloorDiv + :undoc-members: + :members: mapper_method + +.. autoclass:: Remainder + :undoc-members: + :members: mapper_method + +.. autoclass:: Power + :undoc-members: + :members: mapper_method + +Shift operators +--------------- + +.. autoclass:: LeftShift + :undoc-members: + :members: mapper_method + +.. autoclass:: RightShift + :undoc-members: + :members: mapper_method + +Bitwise operators +----------------- + +.. autoclass:: BitwiseNot + :undoc-members: + :members: mapper_method + +.. autoclass:: BitwiseOr + :undoc-members: + :members: mapper_method + +.. autoclass:: BitwiseXor + :undoc-members: + :members: mapper_method + +.. autoclass:: BitwiseAnd + :undoc-members: + :members: mapper_method + +Comparisons and logic +--------------------- + +.. autoclass:: Comparison + :undoc-members: + :members: mapper_method + +.. autoclass:: LogicalNot + :undoc-members: + :members: mapper_method + +.. autoclass:: LogicalAnd + :undoc-members: + :members: mapper_method + +.. autoclass:: LogicalOr + :undoc-members: + :members: mapper_method + +.. autoclass:: If + :undoc-members: + :members: mapper_method + +Code generation helpers +----------------------- + +.. autoclass:: CommonSubexpression + :undoc-members: + :members: mapper_method + +.. autoclass:: cse_scope +.. autofunction:: make_common_subexpression + +Helper functions +---------------- + +.. autofunction:: is_zero +.. autofunction:: is_constant +.. autofunction:: register_constant_class +.. autofunction:: unregister_constant_class +.. autofunction:: variables + +Interaction with :mod:`numpy` arrays +------------------------------------ + +:mod:`numpy.ndarray` instances are supported anywhere in an expression. +In particular, :mod:`numpy` object arrays are useful for capturing +vectors and matrices of :mod:`pymbolic` objects. + +.. autofunction:: make_sym_vector +""" class Expression(object): -- GitLab