From 1b676cfc43556050352beb0eb9fed8a341e0577c Mon Sep 17 00:00:00 2001 From: Andreas Kloeckner Date: Tue, 1 Sep 2020 00:33:55 -0500 Subject: [PATCH] Doc reference fixes --- doc/conf.py | 18 +++- doc/misc.rst | 37 ++++++-- doc/ref_ast.rst | 58 ++++++++++++ doc/ref_containers.rst | 118 ++++++++++++++++++++++++- doc/ref_flow.rst | 27 ++++++ doc/ref_fundamental.rst | 185 ++++++++++++++++++++++++++++++++++++++- doc/ref_schedule.rst | 29 ++++++ doc/reference.rst | 51 ++++++++--- gen_wrap.py | 2 +- islpy/__init__.py | 26 ++++++ src/wrapper/wrap_isl.cpp | 3 + 11 files changed, 524 insertions(+), 30 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index b66f0f2..c158f1b 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -230,7 +230,10 @@ man_pages = [ # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'http://docs.python.org/': None} +intersphinx_mapping = { + "https://docs.python.org/3/": None, + #"https://gmpy2.readthedocs.io/en/latest/": None, + } def autodoc_process_signature(app, what, name, obj, options, signature, @@ -250,6 +253,10 @@ def autodoc_process_signature(app, what, name, obj, options, signature, def autodoc_process_docstring(app, what, name, obj, options, lines): + # clear out redundant pybind-generated member list + if any("Members" in ln for ln in lines): + del lines[:] + from inspect import isclass, isroutine UNDERSCORE_WHITELIST = ["__len__", "__hash__", "__eq__", "__ne__"] if isclass(obj) and obj.__name__[0].isupper(): @@ -269,6 +276,15 @@ def autodoc_process_docstring(app, what, name, obj, options, lines): " * "+gen_method_string(meth) for meth in methods] + lines + for nm in methods: + underscore_autodoc = [] + if nm in UNDERSCORE_WHITELIST: + underscore_autodoc.append(".. automethod:: %s" % nm) + + if underscore_autodoc: + lines.append("") + lines.extend(underscore_autodoc) + def setup(app): app.connect("autodoc-process-docstring", autodoc_process_docstring) diff --git a/doc/misc.rst b/doc/misc.rst index be06a5b..6729b29 100644 --- a/doc/misc.rst +++ b/doc/misc.rst @@ -94,12 +94,12 @@ Version 2016.2 islpy's version control. * Update for isl 0.17 -* Add :func:`make_zero_and_vars` +* Add :func:`islpy.make_zero_and_vars` Version 2016.1.1 ---------------- -* Add :func:`make_zero_and_vars` +* Add :func:`islpy.make_zero_and_vars` * Do not turn on small-integer optimization by default (to avoid build trouble on old compilers) @@ -118,7 +118,7 @@ Version 2014.2 * A large number of previously unavailable functions are now exposed. -* Sebastian Pop's `imath `_ support has +* Sebastian Pop's `imath `__ support has been merged into the version of isl that ships with :mod:`islpy`. This means that unless a user specifically requests a build against GMP, :mod:`islpy` is (a) entirely self-contained and depends only on a C++ compiler and @@ -133,7 +133,7 @@ Version 2014.1 incompatible changes as well. Now :class:`islpy.Val` is used to represent all numbers going - into and out of :mod:`islpy`. :mod:`gmpy` is no longer a dependency + into and out of :mod:`islpy`. ``gmpy`` is no longer a dependency of :mod:`islpy`. The following rules apply for this interface change: * You can pass (up to ``long int``-sized) integers to methods of @@ -156,13 +156,13 @@ Version 2011.3 -------------- * Add :meth:`islpy.Set.project_out_except` and friends. -* Add :meth:`islpy.Set.remove_divs_of_dim_type` and friends. -* :class:`islpy.Dim` was renamed to :class:`islpy.Space` in isl. -* :class:`islpy.Div` was removed and replaced by :class:`islpy.Aff` +* Add ``islpy.Set.remove_divs_of_dim_type`` and friends. +* ``islpy.Dim`` was renamed to :class:`islpy.Space` in isl. +* ``islpy.Div`` was removed and replaced by :class:`islpy.Aff` wherever it was used previously. -* :meth:`islpy.BasicSet.as_set` +* ``islpy.BasicSet.as_set` and - :meth:`islpy.BasicMap.as_map` + ``islpy.BasicMap.as_map`` were removed. * :ref:`automatic-casts` were added. * Support for more Python :class:`set`-like behavior was added. In particular, @@ -186,3 +186,22 @@ Version 2011.1 -------------- * Initial release. + +Documentation Cross-References +------------------------------ + +.. class:: unsigned + + See :class:`int`. + +.. class:: long + + See :class:`int`. + +.. class:: size_t + + See :class:`int`. + +.. class:: double + + See :class:`float`. diff --git a/doc/ref_ast.rst b/doc/ref_ast.rst index 02e5bed..13310e6 100644 --- a/doc/ref_ast.rst +++ b/doc/ref_ast.rst @@ -5,6 +5,25 @@ Reference: Abstract Syntax Trees .. versionadded:: 2014.1 +Symbolic Constants +------------------ + +.. autoclass:: ast_expr_op_type + :members: + :undoc-members: + +.. autoclass:: ast_expr_type + :members: + :undoc-members: + +.. autoclass:: ast_node_type + :members: + :undoc-members: + +.. autoclass:: ast_loop_type + :members: + :undoc-members: + AST Expression -------------- @@ -29,4 +48,43 @@ AST Print Options .. autoclass:: AstPrintOptions :members: +Canonical Names for Internal Module +----------------------------------- + +.. :: + + This should switch to using ``:canonical:`` once Sphinx 4.0 is released. + +.. currentmodule:: islpy._isl + +.. class:: ast_expr_op_type + + See :class:`islpy.ast_expr_op_type`. + +.. class:: ast_expr_type + + See :class:`islpy.ast_expr_type`. + +.. class:: ast_node_type + + See :class:`islpy.ast_node_type`. + +.. class:: ast_loop_type + + See :class:`islpy.ast_loop_type`. + +.. class:: AstExpr + + See :class:`islpy.AstExpr`. + +.. class:: AstNode + + See :class:`islpy.AstNode`. + +.. class:: AstBuild + + See :class:`islpy.AstBuild`. + +.. class:: AstPrintOptions + See :class:`islpy.AstPrintOptions`. diff --git a/doc/ref_containers.rst b/doc/ref_containers.rst index 40bc43c..0f9de49 100644 --- a/doc/ref_containers.rst +++ b/doc/ref_containers.rst @@ -15,6 +15,24 @@ Lists .. autoclass:: BasicSetList :members: +.. autoclass:: AffList + :members: + +.. autoclass:: PwAffList + :members: + +.. autoclass:: PwMultiAffList + :members: + +.. autoclass:: UnionPwAffList + :members: + +.. autoclass:: UnionPwMultiAffList + :members: + +.. autoclass:: ConstraintList + :members: + .. autoclass:: BasicMapList :members: @@ -27,10 +45,7 @@ Lists .. autoclass:: UnionSetList :members: -.. autoclass:: AffList - :members: - -.. autoclass:: UnionPwAffList +.. autoclass:: UnionMapList :members: .. autoclass:: AstExprList @@ -39,9 +54,104 @@ Lists .. autoclass:: AstNodeList :members: +.. autoclass:: PwQPolynomialList + :members: + +.. autoclass:: PwQPolynomialFoldList + :members: + Dictionaries ^^^^^^^^^^^^ .. autoclass:: IdToAstExpr :members: +Multi Types +----------- + +Canonical Names for Internal Module +----------------------------------- + +.. :: + + This should switch to using ``:canonical:`` once Sphinx 4.0 is released. + +.. currentmodule:: islpy._isl + +.. class:: IdList + + See :class:`islpy.IdList`. + +.. class:: ValList + + See :class:`islpy.ValList`. + +.. class:: BasicSetList + + See :class:`islpy.BasicSetList`. + +.. class:: AffList + + See :class:`islpy.AffList`. + +.. class:: PwAffList + + See :class:`islpy.PwAffList`. + +.. class:: PwMultiAffList + + See :class:`islpy.PwMultiAffList`. + +.. class:: UnionPwAffList + + See :class:`islpy.UnionPwAffList`. + +.. class:: UnionPwMultiAffList + + See :class:`islpy.UnionPwMultiAffList`. + +.. class:: ConstraintList + + See :class:`islpy.ConstraintList`. + +.. class:: BasicMapList + + See :class:`islpy.BasicMapList`. + +.. class:: SetList + + See :class:`islpy.SetList`. + +.. class:: MapList + + See :class:`islpy.MapList`. + +.. class:: UnionSetList + + See :class:`islpy.UnionSetList`. + +.. class:: UnionMapList + + See :class:`islpy.UnionMapList`. + +.. class:: AstExprList + + See :class:`islpy.AstExprList`. + +.. class:: AstNodeList + + See :class:`islpy.AstNodeList`. + +.. class:: IdToAstExpr + + See :class:`islpy.IdToAstExpr`. + +.. class:: PwQPolynomialList + + See :class:`islpy.PwQPolynomialList`. + +.. class:: PwQPolynomialFoldList + + See :class:`islpy.PwQPolynomialFoldList`. + +.. vim: sw=4 diff --git a/doc/ref_flow.rst b/doc/ref_flow.rst index 65ab844..b583364 100644 --- a/doc/ref_flow.rst +++ b/doc/ref_flow.rst @@ -33,4 +33,31 @@ Union Flow .. autoclass:: UnionFlow :members: +Canonical Names for Internal Module +----------------------------------- +.. :: + + This should switch to using ``:canonical:`` once Sphinx 4.0 is released. + +.. currentmodule:: islpy._isl + +.. class:: AccessInfo + + See :class:`islpy.AccessInfo`. + +.. class:: UnionAccessInfo + + See :class:`islpy.UnionAccessInfo`. + +.. class:: Restriction + + See :class:`islpy.Restriction`. + +.. class:: Flow + + See :class:`islpy.Flow`. + +.. class:: UnionFlow + + See :class:`islpy.UnionFlow`. diff --git a/doc/ref_fundamental.rst b/doc/ref_fundamental.rst index f4e59e7..f769771 100644 --- a/doc/ref_fundamental.rst +++ b/doc/ref_fundamental.rst @@ -15,10 +15,13 @@ Id .. autoclass:: Id :members: +.. autoclass:: MultiId + :members: + Space ----- -(formerly called :class:`Dim`. A compatibility alias is in place.) +(formerly called ``Dim``. A compatibility alias is in place.) .. autoclass:: Space :members: @@ -41,6 +44,8 @@ Value .. autoclass:: Val :members: + .. automethod:: to_python + Multi-Value ----------- @@ -119,12 +124,24 @@ Vertices .. autoclass:: Vertices :members: +StrideInfo +---------- + +.. autoclass:: StrideInfo + :members: + Cell ---- .. autoclass:: Cell :members: +Fixed Box +--------- + +.. autoclass:: FixedBox + :members: + Quasi-Affine Expressions ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -168,6 +185,12 @@ Piecewise Multiple Affine Expression .. autoclass:: PwMultiAff :members: +Multiple Piecewise Affine Expression +------------------------------------ + +.. autoclass:: MultiPwAff + :members: + Union of Piecewise Multiple Affine Expressions ---------------------------------------------- @@ -219,3 +242,163 @@ UnionPwQPolynomialFold .. autoclass:: UnionPwQPolynomialFold :members: +Canonical Names for Internal Module +----------------------------------- + +.. :: + + This should switch to using ``:canonical:`` once Sphinx 4.0 is released. + +.. currentmodule:: islpy._isl + +.. class:: Context + + See :class:`islpy.Context`. + +.. class:: Id + + See :class:`islpy.Id`. + +.. class:: MultiId + + See :class:`islpy.MultiId`. + +.. class:: Space + + See :class:`islpy.Space`. + +.. class:: LocalSpace + + See :class:`islpy.LocalSpace`. + +.. class:: Constraint + + See :class:`islpy.Constraint`. + +.. class:: Val + + See :class:`islpy.Val`. + +.. class:: MultiVal + + See :class:`islpy.MultiVal`. + +.. class:: Vec + + See :class:`islpy.Vec`. + +.. class:: Mat + + See :class:`islpy.Mat`. + +.. class:: BasicSet + + See :class:`islpy.BasicSet`. + +.. class:: BasicMap + + See :class:`islpy.BasicMap`. + +.. class:: Set + + See :class:`islpy.Set`. + +.. class:: Map + + See :class:`islpy.Map`. + +.. class:: UnionSet + + See :class:`islpy.UnionSet`. + +.. class:: UnionMap + + See :class:`islpy.UnionMap`. + +.. class:: Point + + See :class:`islpy.Point`. + +.. class:: Vertex + + See :class:`islpy.Vertex`. + +.. class:: Vertices + + See :class:`islpy.Vertices`. + +.. class:: StrideInfo + + See :class:`islpy.StrideInfo`. + +.. class:: Cell + + See :class:`islpy.Cell`. + +.. class:: FixedBox + + See :class:`islpy.FixedBox`. + +.. class:: Aff + + See :class:`islpy.Aff`. + +.. class:: Div + + See :class:`islpy.Aff` (not a typo!). + +.. class:: PwAff + + See :class:`islpy.PwAff`. + +.. class:: UnionPwAff + + See :class:`islpy.UnionPwAff`. + +.. class:: MultiUnionPwAff + + See :class:`islpy.MultiUnionPwAff`. + +.. class:: MultiAff + + See :class:`islpy.MultiAff`. + +.. class:: PwMultiAff + + See :class:`islpy.PwMultiAff`. + +.. class:: MultiPwAff + + See :class:`islpy.MultiPwAff`. + +.. class:: UnionPwMultiAff + + See :class:`islpy.UnionPwMultiAff`. + +.. class:: Term + + See :class:`islpy.Term`. + +.. class:: QPolynomial + + See :class:`islpy.QPolynomial`. + +.. class:: PwQPolynomial + + See :class:`islpy.PwQPolynomial`. + +.. class:: UnionPwQPolynomial + + See :class:`islpy.UnionPwQPolynomial`. + +.. class:: QPolynomialFold + + See :class:`islpy.QPolynomialFold`. + +.. class:: PwQPolynomialFold + + See :class:`islpy.PwQPolynomialFold`. + +.. class:: UnionPwQPolynomialFold + + See :class:`islpy.UnionPwQPolynomialFold`. diff --git a/doc/ref_schedule.rst b/doc/ref_schedule.rst index c9a93d8..10d766c 100644 --- a/doc/ref_schedule.rst +++ b/doc/ref_schedule.rst @@ -6,6 +6,10 @@ Reference: Scheduling Schedule -------- +.. autoclass:: schedule_node_type + :members: + :undoc-members: + .. autoclass:: Schedule :members: @@ -20,3 +24,28 @@ ScheduleConstraints .. autoclass:: ScheduleConstraints :members: + +Canonical Names for Internal Module +----------------------------------- + +.. :: + + This should switch to using ``:canonical:`` once Sphinx 4.0 is released. + +.. currentmodule:: islpy._isl + +.. class:: schedule_node_type + + See :class:`islpy.schedule_node_type`. + +.. class:: Schedule + + See :class:`islpy.Schedule`. + +.. class:: ScheduleNode + + See :class:`islpy.ScheduleNode`. + +.. class:: ScheduleConstraints + + See :class:`islpy.ScheduleConstraints`. diff --git a/doc/reference.rst b/doc/reference.rst index 7ef6bf4..37d6f47 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -116,18 +116,6 @@ Symbolic Constants :undoc-members: :exclude-members: names, values -.. autoclass:: ast_op_type - :members: - :undoc-members: - -.. autoclass:: ast_expr_type - :members: - :undoc-members: - -.. autoclass:: ast_node_type - :members: - :undoc-members: - .. autoclass:: format :members: :undoc-members: @@ -136,8 +124,6 @@ Symbolic Constants :members: :undoc-members: - - Output ^^^^^^ @@ -150,4 +136,41 @@ Helper functions .. autofunction:: align_spaces .. autofunction:: align_two +Canonical Names for Internal Module +----------------------------------- + +.. :: + + This should switch to using ``:canonical:`` once Sphinx 4.0 is released. + +.. currentmodule:: islpy._isl + +.. class:: stat + + A status result. + +.. class:: error + + See :class:`islpy.error`. + +.. class:: dim_type + + See :class:`islpy.dim_type`. + +.. class:: fold + + See :class:`islpy.fold`. + +.. class:: format + + See :class:`islpy.format`. + +.. class:: yaml_style + + See :class:`islpy.yaml_style`. + +.. class:: Printer + + See :class:`islpy.Printer`. + .. vim: sw=4 diff --git a/gen_wrap.py b/gen_wrap.py index ab31931..6e8a162 100644 --- a/gen_wrap.py +++ b/gen_wrap.py @@ -165,7 +165,6 @@ PART_TO_CLASSES = { # lists "id_list", "val_list", "basic_set_list", "basic_map_list", "set_list", "map_list", - "union_set_list", "constraint_list", "aff_list", "pw_aff_list", "pw_multi_aff_list", "ast_expr_list", "ast_node_list", @@ -173,6 +172,7 @@ PART_TO_CLASSES = { "pw_qpolynomial_fold_list", "union_pw_aff_list", "union_pw_multi_aff_list", + "union_set_list", "union_map_list", # maps diff --git a/islpy/__init__.py b/islpy/__init__.py index 3c2a5db..b15ae7b 100644 --- a/islpy/__init__.py +++ b/islpy/__init__.py @@ -41,14 +41,25 @@ UnionSetList = _isl.UnionSetList ConstraintList = _isl.ConstraintList AffList = _isl.AffList PwAffList = _isl.PwAffList +PwMultiAffList = _isl.PwMultiAffList AstExprList = _isl.AstExprList AstNodeList = _isl.AstNodeList + +PwQPolynomialList = _isl.PwQPolynomialList +PwQPolynomialFoldList = _isl.PwQPolynomialFoldList + +UnionPwAffList = _isl.UnionPwAffList +UnionPwMultiAffList = _isl.UnionPwMultiAffList +UnionMapList = _isl.UnionMapList +UnionSetList = _isl.UnionSetList + IdToAstExpr = _isl.IdToAstExpr Printer = _isl.Printer Val = _isl.Val MultiVal = _isl.MultiVal Vec = _isl.Vec Mat = _isl.Mat +FixedBox = _isl.FixedBox Aff = _isl.Aff PwAff = _isl.PwAff UnionPwAff = _isl.UnionPwAff @@ -59,6 +70,7 @@ UnionPwMultiAff = _isl.UnionPwMultiAff UnionPwAffList = _isl.UnionPwAffList MultiUnionPwAff = _isl.MultiUnionPwAff Id = _isl.Id +MultiId = _isl.MultiId Constraint = _isl.Constraint Space = _isl.Space LocalSpace = _isl.LocalSpace @@ -1325,4 +1337,18 @@ class SuppressedWarnings: self.ctx.set_on_error(self.prev_on_error) +# {{{ give sphinx something to import so we can produce docs + +def _define_doc_link_names(): + class Div: + pass + + _isl.Div = Div + + +_define_doc_link_names() + +# }}} + + # vim: foldmethod=marker diff --git a/src/wrapper/wrap_isl.cpp b/src/wrapper/wrap_isl.cpp index 3871607..bc5fef3 100644 --- a/src/wrapper/wrap_isl.cpp +++ b/src/wrapper/wrap_isl.cpp @@ -12,6 +12,9 @@ namespace isl PYBIND11_MODULE(_isl, m) { + py::options options; + options.disable_function_signatures(); + static py::exception ISLError(m, "Error", NULL); py::register_exception_translator( [](std::exception_ptr p) -- GitLab