From 89ed130335346364006f0e41936c4d563e1ec5f7 Mon Sep 17 00:00:00 2001 From: Matthias Volk Date: Mon, 30 Apr 2018 17:43:07 +0200 Subject: [PATCH] Extended documentation --- doc/source/advanced_topics.rst | 6 +- doc/source/api.rst | 17 +++++ .../{code_stormpy_core.rst => api/core.rst} | 8 --- doc/source/api/dft.rst | 7 ++ doc/source/api/exceptions.rst | 7 ++ doc/source/api/info.rst | 7 ++ doc/source/api/logic.rst | 7 ++ doc/source/api/pars.rst | 7 ++ doc/source/api/storage.rst | 7 ++ doc/source/api/utility.rst | 7 ++ doc/source/code_stormpy_logic.rst | 12 ---- doc/source/code_stormpy_storage.rst | 11 ---- doc/source/conf.py | 2 +- doc/source/contributors.rst | 3 +- doc/source/{ => doc}/building_models.rst | 0 doc/source/{ => doc}/reward_models.rst | 0 doc/source/{ => doc}/shortest_paths.rst | 0 doc/source/getting_started.rst | 10 +-- doc/source/index.rst | 12 +--- doc/source/installation.rst | 66 ++++++++++++++----- 20 files changed, 129 insertions(+), 67 deletions(-) create mode 100644 doc/source/api.rst rename doc/source/{code_stormpy_core.rst => api/core.rst} (53%) create mode 100644 doc/source/api/dft.rst create mode 100644 doc/source/api/exceptions.rst create mode 100644 doc/source/api/info.rst create mode 100644 doc/source/api/logic.rst create mode 100644 doc/source/api/pars.rst create mode 100644 doc/source/api/storage.rst create mode 100644 doc/source/api/utility.rst delete mode 100644 doc/source/code_stormpy_logic.rst delete mode 100644 doc/source/code_stormpy_storage.rst rename doc/source/{ => doc}/building_models.rst (100%) rename doc/source/{ => doc}/reward_models.rst (100%) rename doc/source/{ => doc}/shortest_paths.rst (100%) diff --git a/doc/source/advanced_topics.rst b/doc/source/advanced_topics.rst index 124c702..7c5d0c0 100644 --- a/doc/source/advanced_topics.rst +++ b/doc/source/advanced_topics.rst @@ -8,6 +8,6 @@ This guide is a collection of examples meant to bridge the gap between the getti :maxdepth: 2 :caption: Contents: - building_models - reward_models - shortest_paths \ No newline at end of file + doc/building_models + doc/reward_models + doc/shortest_paths \ No newline at end of file diff --git a/doc/source/api.rst b/doc/source/api.rst new file mode 100644 index 0000000..f9144c4 --- /dev/null +++ b/doc/source/api.rst @@ -0,0 +1,17 @@ +Stormpy API Reference +==================================== +Work in progress! + +.. toctree:: + :maxdepth: 2 + :caption: Modules: + + api/core + api/info + api/exceptions + api/logic + api/storage + api/utility + + api/dft + api/pars diff --git a/doc/source/code_stormpy_core.rst b/doc/source/api/core.rst similarity index 53% rename from doc/source/code_stormpy_core.rst rename to doc/source/api/core.rst index 4f26fa9..b9a41a1 100644 --- a/doc/source/code_stormpy_core.rst +++ b/doc/source/api/core.rst @@ -5,11 +5,3 @@ Stormpy.core :members: :undoc-members: :imported-members: - -Core members -========================= - - -.. automodule:: stormpy.core - :members: - :undoc-members: diff --git a/doc/source/api/dft.rst b/doc/source/api/dft.rst new file mode 100644 index 0000000..331f60c --- /dev/null +++ b/doc/source/api/dft.rst @@ -0,0 +1,7 @@ +Stormpy.dft +************************** + +.. automodule:: stormpy.dft + :members: + :undoc-members: + :imported-members: diff --git a/doc/source/api/exceptions.rst b/doc/source/api/exceptions.rst new file mode 100644 index 0000000..8a3e2b2 --- /dev/null +++ b/doc/source/api/exceptions.rst @@ -0,0 +1,7 @@ +Stormpy.exceptions +************************** + +.. automodule:: stormpy.exceptions + :members: + :undoc-members: + :imported-members: diff --git a/doc/source/api/info.rst b/doc/source/api/info.rst new file mode 100644 index 0000000..8421b2b --- /dev/null +++ b/doc/source/api/info.rst @@ -0,0 +1,7 @@ +Stormpy.info +************************** + +.. automodule:: stormpy.info + :members: + :undoc-members: + :imported-members: diff --git a/doc/source/api/logic.rst b/doc/source/api/logic.rst new file mode 100644 index 0000000..84d34a9 --- /dev/null +++ b/doc/source/api/logic.rst @@ -0,0 +1,7 @@ +Stormpy.logic +************************** + +.. automodule:: stormpy.logic + :members: + :undoc-members: + :imported-members: diff --git a/doc/source/api/pars.rst b/doc/source/api/pars.rst new file mode 100644 index 0000000..2c66395 --- /dev/null +++ b/doc/source/api/pars.rst @@ -0,0 +1,7 @@ +Stormpy.pars +************************** + +.. automodule:: stormpy.pars + :members: + :undoc-members: + :imported-members: diff --git a/doc/source/api/storage.rst b/doc/source/api/storage.rst new file mode 100644 index 0000000..5281904 --- /dev/null +++ b/doc/source/api/storage.rst @@ -0,0 +1,7 @@ +Stormpy.storage +************************** + +.. automodule:: stormpy.storage + :members: + :undoc-members: + :imported-members: diff --git a/doc/source/api/utility.rst b/doc/source/api/utility.rst new file mode 100644 index 0000000..6bfe305 --- /dev/null +++ b/doc/source/api/utility.rst @@ -0,0 +1,7 @@ +Stormpy.utility +************************** + +.. automodule:: stormpy.utility + :members: + :undoc-members: + :imported-members: diff --git a/doc/source/code_stormpy_logic.rst b/doc/source/code_stormpy_logic.rst deleted file mode 100644 index 51c4daf..0000000 --- a/doc/source/code_stormpy_logic.rst +++ /dev/null @@ -1,12 +0,0 @@ -Stormpy.logic -************************** - -.. automodule:: stormpy - - -Members -========================= - - -.. automodule:: stormpy.logic.logic - :members: diff --git a/doc/source/code_stormpy_storage.rst b/doc/source/code_stormpy_storage.rst deleted file mode 100644 index 666f940..0000000 --- a/doc/source/code_stormpy_storage.rst +++ /dev/null @@ -1,11 +0,0 @@ -Stormpy.storage -************************** - -.. automodule:: stormpy - -Members -============================== - -.. automodule:: stormpy.storage.storage - :members: - diff --git a/doc/source/conf.py b/doc/source/conf.py index 2fbcfa8..c1a41d1 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -56,7 +56,7 @@ master_doc = 'index' # General information about the project. project = 'stormpy' -copyright = '2016--2017 Moves RWTH Aachen' +copyright = '2016--2018 Moves RWTH Aachen' author = 'Sebastian Junges, Matthias Volk' # The version info for the project you're documenting, acts as replacement for diff --git a/doc/source/contributors.rst b/doc/source/contributors.rst index 464d72b..0961349 100644 --- a/doc/source/contributors.rst +++ b/doc/source/contributors.rst @@ -2,7 +2,8 @@ Contributors ************** -Stormpy is an extension to `Storm `_. As a consequence, developers of Storm contributed significantly to the functionality offered by these Python bindings. +Stormpy is an extension to `Storm `_. +As a consequence, developers of Storm contributed significantly to the functionality offered by these Python bindings. The bindings themselves have been developed by (lexicographically ordered): * Sebastian Junges diff --git a/doc/source/building_models.rst b/doc/source/doc/building_models.rst similarity index 100% rename from doc/source/building_models.rst rename to doc/source/doc/building_models.rst diff --git a/doc/source/reward_models.rst b/doc/source/doc/reward_models.rst similarity index 100% rename from doc/source/reward_models.rst rename to doc/source/doc/reward_models.rst diff --git a/doc/source/shortest_paths.rst b/doc/source/doc/shortest_paths.rst similarity index 100% rename from doc/source/shortest_paths.rst rename to doc/source/doc/shortest_paths.rst diff --git a/doc/source/getting_started.rst b/doc/source/getting_started.rst index b577e11..1649cc6 100644 --- a/doc/source/getting_started.rst +++ b/doc/source/getting_started.rst @@ -11,15 +11,17 @@ This guide is intended for people which have a basic understanding of probabilis `Storm website `_. While we assume some very basic programming concepts, we refrain from using more advanced concepts of python throughout the guide. -We start with a selection of high-level constructs in stormpy, and go into more details afterwards. More in-depth examples can be found in the :doc:`advanced_examples`. +We start with a selection of high-level constructs in stormpy, and go into more details afterwards. More in-depth examples can be found in the :doc:`advanced_topics`. .. seealso:: The code examples are also given in the `examples/ `_ folder. These boxes throughout the text will tell you which example contains the code discussed. -In order to do this, we import stormpy:: +We start by launching the python 3 interpreter:: + + $ python3 + +First we import stormpy:: >>> import stormpy - >>> import stormpy.core - Building models ------------------------------------------------ diff --git a/doc/source/index.rst b/doc/source/index.rst index 76040e8..74a137d 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -19,16 +19,8 @@ Stormpy is a set of python bindings for the probabilistic model checker `Storm < advanced_topics contributors - -Stormpy API Reference -==================================== -.. toctree:: - :maxdepth: 2 - :caption: Modules: - - code_stormpy_core - code_stormpy_logic - code_stormpy_storage + +.. include:: api.rst Indices and tables diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 69d2915..858da51 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -7,28 +7,46 @@ Requirements Before installing stormpy, make sure -- `pycarl `_ -- `Storm `_ +- Python 3 is available on your system. Stormpy does not work with python 2. +- `pycarl `_ is available. +- `Storm `_ is available on your system. -are both available on your system. To avoid issues, we suggest that both use the same version of `carl `_. +To avoid issues, we suggest that both pycarl and Storm use the same version of `carl `_. The simplest way of ensuring this is to first install carl as explained in the `Storm installation guide `_. You can then install Storm and pycarl independently. -.. topic:: Virtual Environments - - Virtual environments create isolated environments for your projects. This helps to keep your system clean, work with different versions of packages and different versions of python. While it is not required, we recommend the use of - such virtual environments. To get you started, we recommend `this guide `_ or `this primer `_. - Installation Steps ==================== +Virtual Environments +-------------------- + +Virtual environments create isolated environments for your projects. +This helps to keep your system clean, work with different versions of packages and different version of python. +While it is not required, we recommend the use of such virtual environments. To get you started, we recommend +`this guide `_ or +`this primer `_. + +In short you can create a virtual environment ``env`` with:: + + $ pip install virtualenv + $ virtualenv -p python3 env + $ source env/bin/activate + +The last step activates the virtual environment. +Whenever using the environment the console prompt is prefixed with ``(env)``. + + +Building stormpy +---------------- + Clone stormpy into any suitable location:: $ git clone https://github.com/moves-rwth/stormpy.git $ cd stormpy -Here, build stormpy in develop mode using your favourite python distribution way of installing: e.g.:: +Build stormpy in develop mode using your favourite python distribution way of installing: e.g.:: $ python3 setup.py develop @@ -37,17 +55,31 @@ or:: $ pip install -ve . -.. topic:: Specifying which Storm library to use +Optional build arguments +^^^^^^^^^^^^^^^^^^^^^^^^ + +The build step also takes optional arguments for a more advanced configuration of stormpy. + +* *Specifying which Storm library to use* + + If you have multiple versions of Storm or cmake is not able to find your Storm version, + you can specify the ``--storm-dir YOUR-PATH-TO-STORM`` flag in the ``build_ext`` step:: - If you have multiple versions of Storm or cmake is not able to find your Storm version, - you can specify the `--storm-dir YOUR-PATH-TO-STORM` flag in the build_ext step:: - $ python3 setup.py build_ext --storm-dir YOUR-PATH-TO-STORM develop - + +* *Building stormpy in debug mode* + + If you want to build stormpy in debug mode you can add the ``--debug`` flag in the ``build_ext`` step:: + + $ python3 setup.py build_ext --debug develop + + +Testing stormpy installation +---------------------------- + After building, you can run the test files by:: py.test tests/ -If tests pass, you can continue with our :doc:`getting_started`. - - +If the tests pass, you can now use stormpy. +To get started, continue with our :doc:`getting_started`, consult the test files in ``tests/`` or the :doc:`api` (work in progress).