diff --git a/.gitignore b/.gitignore index 894675ce32..bffa7be344 100644 --- a/.gitignore +++ b/.gitignore @@ -14,3 +14,4 @@ cmake-build-debug/ .cache/ .DS_Store .venv/ +doc/source/api/generated/ diff --git a/doc/source/_templates/autosummary/class.rst b/doc/source/_templates/autosummary/class.rst new file mode 100644 index 0000000000..28572371a9 --- /dev/null +++ b/doc/source/_templates/autosummary/class.rst @@ -0,0 +1,9 @@ +{{ objname | escape | underline }} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + :members: + :undoc-members: + :inherited-members: + :show-inheritance: diff --git a/doc/source/_templates/autosummary/function.rst b/doc/source/_templates/autosummary/function.rst new file mode 100644 index 0000000000..3fe9858d79 --- /dev/null +++ b/doc/source/_templates/autosummary/function.rst @@ -0,0 +1,5 @@ +{{ objname | escape | underline }} + +.. currentmodule:: {{ module }} + +.. auto{{ objtype }}:: {{ objname }} diff --git a/doc/source/_templates/autosummary/module.rst b/doc/source/_templates/autosummary/module.rst new file mode 100644 index 0000000000..1db6de2679 --- /dev/null +++ b/doc/source/_templates/autosummary/module.rst @@ -0,0 +1,58 @@ +{#- Only list the members that belong to this module (see filter_api_members in conf.py) -#} +{%- set attributes = filter_api_members(fullname, attributes) -%} +{%- set functions = filter_api_members(fullname, functions) -%} +{%- set classes = filter_api_members(fullname, classes) -%} +{%- set exceptions = filter_api_members(fullname, exceptions) -%} +{{ fullname | escape | underline}} + +.. automodule:: {{ fullname }} + + {% block attributes %} + {%- if attributes %} + .. rubric:: {{ _('Module Attributes') }} + + .. autosummary:: + :toctree: + {% for item in attributes %} + {{ item }} + {%- endfor %} + {% endif %} + {%- endblock %} + + {%- block functions %} + {%- if functions %} + .. rubric:: {{ _('Functions') }} + + .. autosummary:: + :toctree: + {% for item in functions %} + {{ item }} + {%- endfor %} + {% endif %} + {%- endblock %} + + {%- block classes %} + {%- if classes %} + .. rubric:: {{ _('Classes') }} + + .. autosummary:: + :toctree: + :template: autosummary/class.rst + {% for item in classes %} + {{ item }} + {%- endfor %} + {% endif %} + {%- endblock %} + + {%- block exceptions %} + {%- if exceptions %} + .. rubric:: {{ _('Exceptions') }} + + .. autosummary:: + :toctree: + :template: autosummary/class.rst + {% for item in exceptions %} + {{ item }} + {%- endfor %} + {% endif %} + {%- endblock %} diff --git a/doc/source/api.md b/doc/source/api.md index b1cbb3b4ed..5d47201794 100644 --- a/doc/source/api.md +++ b/doc/source/api.md @@ -2,24 +2,36 @@ Work in progress! -:::{toctree} -:maxdepth: 2 -:caption: Stormpy modules: +```{eval-rst} +.. autosummary:: + :toctree: api/generated + :template: autosummary/module.rst + :caption: Stormpy modules: -api/core -api/info -api/exceptions -api/logic -api/storage -api/utility + stormpy + stormpy.storage + stormpy.logic + stormpy.dft + stormpy.gspn + stormpy.pars + stormpy.pomdp + stormpy.info + stormpy.exceptions + stormpy.utility +``` -api/dft -api/gspn -api/pars -api/pomdp +```{eval-rst} +.. autosummary:: + :toctree: api/generated + :template: autosummary/module.rst + :caption: Pycarl modules: -api/pycarl/core -api/pycarl/convert -api/pycarl/formula -api/pycarl/parse -::: \ No newline at end of file + stormpy.pycarl + stormpy.pycarl.gmp + stormpy.pycarl.cln + stormpy.pycarl.formula + stormpy.pycarl.gmp.formula + stormpy.pycarl.cln.formula + stormpy.pycarl.parse + stormpy.pycarl.convert +``` diff --git a/doc/source/api/core.rst b/doc/source/api/core.rst deleted file mode 100644 index 862d19ee42..0000000000 --- a/doc/source/api/core.rst +++ /dev/null @@ -1,8 +0,0 @@ -Stormpy.core -************************** - -.. automodule:: stormpy - :members: - :undoc-members: - :imported-members: - :exclude-members: deprecated diff --git a/doc/source/api/dft.rst b/doc/source/api/dft.rst deleted file mode 100644 index 1d2ab641df..0000000000 --- a/doc/source/api/dft.rst +++ /dev/null @@ -1,8 +0,0 @@ -Stormpy.dft -************************** - -.. automodule:: stormpy.dft - :members: - :undoc-members: - :imported-members: - :exclude-members: deprecated diff --git a/doc/source/api/exceptions.rst b/doc/source/api/exceptions.rst deleted file mode 100644 index ff37137a5a..0000000000 --- a/doc/source/api/exceptions.rst +++ /dev/null @@ -1,8 +0,0 @@ -Stormpy.exceptions -************************** - -.. automodule:: stormpy.exceptions - :members: - :undoc-members: - :imported-members: - :exclude-members: deprecated diff --git a/doc/source/api/gspn.rst b/doc/source/api/gspn.rst deleted file mode 100644 index f5317da559..0000000000 --- a/doc/source/api/gspn.rst +++ /dev/null @@ -1,8 +0,0 @@ -Stormpy.gspn -************************** - -.. automodule:: stormpy.gspn - :members: - :undoc-members: - :imported-members: - :exclude-members: deprecated diff --git a/doc/source/api/info.rst b/doc/source/api/info.rst deleted file mode 100644 index d7a6409fcd..0000000000 --- a/doc/source/api/info.rst +++ /dev/null @@ -1,8 +0,0 @@ -Stormpy.info -************************** - -.. automodule:: stormpy.info - :members: - :undoc-members: - :imported-members: - :exclude-members: deprecated diff --git a/doc/source/api/logic.rst b/doc/source/api/logic.rst deleted file mode 100644 index ea8ddacc3e..0000000000 --- a/doc/source/api/logic.rst +++ /dev/null @@ -1,8 +0,0 @@ -Stormpy.logic -************************** - -.. automodule:: stormpy.logic - :members: - :undoc-members: - :imported-members: - :exclude-members: deprecated diff --git a/doc/source/api/pars.rst b/doc/source/api/pars.rst deleted file mode 100644 index c0954de512..0000000000 --- a/doc/source/api/pars.rst +++ /dev/null @@ -1,8 +0,0 @@ -Stormpy.pars -************************** - -.. automodule:: stormpy.pars - :members: - :undoc-members: - :imported-members: - :exclude-members: deprecated diff --git a/doc/source/api/pomdp.rst b/doc/source/api/pomdp.rst deleted file mode 100644 index e8eb8cae36..0000000000 --- a/doc/source/api/pomdp.rst +++ /dev/null @@ -1,7 +0,0 @@ -Stormpy.pomdp -************************** - -.. automodule:: stormpy.pomdp - :members: - :undoc-members: - :imported-members: diff --git a/doc/source/api/pycarl/convert.rst b/doc/source/api/pycarl/convert.rst deleted file mode 100644 index 0588011288..0000000000 --- a/doc/source/api/pycarl/convert.rst +++ /dev/null @@ -1,12 +0,0 @@ -Pycarl convert -************************** - - -Number conversion ---------------------------- - -.. automodule:: stormpy.pycarl.convert - :members: - :undoc-members: - :imported-members: - :exclude-members: deprecated diff --git a/doc/source/api/pycarl/core.rst b/doc/source/api/pycarl/core.rst deleted file mode 100644 index d3a2ad954b..0000000000 --- a/doc/source/api/pycarl/core.rst +++ /dev/null @@ -1,30 +0,0 @@ -Pycarl core -************************** - - -Number independent types ---------------------------- - -.. automodule:: stormpy.pycarl - :members: - :undoc-members: - :imported-members: - :exclude-members: deprecated - -Number dependent types (gmp) ------------------------------- - -.. automodule:: stormpy.pycarl.gmp - :members: - :undoc-members: - :imported-members: - :exclude-members: deprecated - -Number dependent types (cln) ------------------------------- - -.. automodule:: stormpy.pycarl.cln - :members: - :undoc-members: - :imported-members: - :exclude-members: deprecated diff --git a/doc/source/api/pycarl/formula.rst b/doc/source/api/pycarl/formula.rst deleted file mode 100644 index 44e1cd46cc..0000000000 --- a/doc/source/api/pycarl/formula.rst +++ /dev/null @@ -1,30 +0,0 @@ -Pycarl formula -************************** - - -Number independent types ---------------------------- - -.. automodule:: stormpy.pycarl.formula - :members: - :undoc-members: - :imported-members: - :exclude-members: deprecated - -Number dependent types (gmp) ------------------------------- - -.. automodule:: stormpy.pycarl.gmp.formula - :members: - :undoc-members: - :imported-members: - :exclude-members: deprecated - -Number dependent types (cln) ------------------------------- - -.. automodule:: stormpy.pycarl.cln.formula - :members: - :undoc-members: - :imported-members: - :exclude-members: deprecated diff --git a/doc/source/api/pycarl/parse.rst b/doc/source/api/pycarl/parse.rst deleted file mode 100644 index 9076e6f9dc..0000000000 --- a/doc/source/api/pycarl/parse.rst +++ /dev/null @@ -1,30 +0,0 @@ -Pycarl parse -************************** - - -Number independent types ---------------------------- - -.. automodule:: stormpy.pycarl.parse - :members: - :undoc-members: - :imported-members: - :exclude-members: deprecated - -Number dependent types (gmp) ------------------------------- - -.. automodule:: stormpy.pycarl.gmp.parse - :members: - :undoc-members: - :imported-members: - :exclude-members: deprecated - -Number dependent types (cln) ------------------------------- - -.. automodule:: stormpy.pycarl.cln.parse - :members: - :undoc-members: - :imported-members: - :exclude-members: deprecated diff --git a/doc/source/api/storage.rst b/doc/source/api/storage.rst deleted file mode 100644 index f794517a03..0000000000 --- a/doc/source/api/storage.rst +++ /dev/null @@ -1,8 +0,0 @@ -Stormpy.storage -************************** - -.. automodule:: stormpy.storage - :members: - :undoc-members: - :imported-members: - :exclude-members: deprecated diff --git a/doc/source/api/utility.rst b/doc/source/api/utility.rst deleted file mode 100644 index 051cbdb1b7..0000000000 --- a/doc/source/api/utility.rst +++ /dev/null @@ -1,8 +0,0 @@ -Stormpy.utility -************************** - -.. automodule:: stormpy.utility - :members: - :undoc-members: - :imported-members: - :exclude-members: deprecated diff --git a/doc/source/conf.py b/doc/source/conf.py index 4f2469cdd8..255d43c68a 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -4,6 +4,8 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html # Needed for version information +import sys + import stormpy # -- Project information ----------------------------------------------------- @@ -21,6 +23,7 @@ extensions = [ "sphinx.ext.autodoc", + "sphinx.ext.autosummary", "sphinx.ext.autosectionlabel", #'sphinx.ext.intersphinx', "sphinx.ext.githubpages", @@ -33,6 +36,53 @@ # Autodoc options autoclass_content = "both" # Add documentation for both the class and __init__ +# Autosummary options +# Also list members that are re-exported (e.g. classes defined in the +# compiled _logic module and imported into stormpy.logic) +autosummary_imported_members = True + +# For modules that re-export members of other modules: the members that should +# be listed on the module's autosummary page, identified by their __module__. +# All other module pages list all their members. +_MEMBER_MODULES = { + # The top-level stormpy package also re-exports the members of several + # submodules (e.g. storage and logic). Its page (the core API) only lists + # the members defined in stormpy itself or in the compiled _core extension. + "stormpy": {"stormpy", "stormpy._core"}, + # The number-independent core types live in the compiled _pycarl_core module. + "stormpy.pycarl": {"stormpy.pycarl", "stormpy.pycarl._pycarl_core"}, + # The number-dependent formula types are bound under the shared formula module. + "stormpy.pycarl.gmp.formula": {"stormpy.pycarl.formula"}, + "stormpy.pycarl.cln.formula": {"stormpy.pycarl.formula"}, + # Utility modules re-export pycarl helpers. + "stormpy.pycarl.convert": {"stormpy.pycarl.convert"}, + "stormpy.pycarl.parse": {"stormpy.pycarl.parse"}, +} + + +def _filter_api_members(module, members): + """ + Filter the members listed on the autosummary page of a module. + + To document every member only on the page of the module it belongs to, + the pages of the modules in _MEMBER_MODULES (which re-export members of + other modules) only list the members defined in the given modules. + """ + accepted = _MEMBER_MODULES.get(module) + if accepted is None: + return members + module_obj = sys.modules[module] + return [name for name in members if getattr(getattr(module_obj, name, None), "__module__", None) in accepted] + + +# Variables (and callables) available in autosummary templates +autosummary_context = { + "filter_api_members": _filter_api_members, +} + +# Wrap long signatures instead of scrolling them +python_maximum_signature_line_length = 100 + templates_path = ["_templates"] exclude_patterns = [] diff --git a/lib/stormpy/__init__.py b/lib/stormpy/__init__.py index c54e6d0ed8..205c3d9b20 100644 --- a/lib/stormpy/__init__.py +++ b/lib/stormpy/__init__.py @@ -1,10 +1,11 @@ from ._config import * -from . import _core -from ._core import * from . import storage from .storage import * +from . import logic from .logic import * +from . import _core +from ._core import * from . import exceptions from enum import Enum