diff --git a/.gitignore b/.gitignore index 351f53ba..4ee04678 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,7 @@ __pycache__/ *.egg-info dist/ build/ +docs/_build/ # mac *DS_Store # dev diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..6a8277b6 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,32 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.12" + # You can also specify other tool versions: + # nodejs: "19" + # rust: "1.64" + # golang: "1.19" + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: docs/conf.py + +# Optionally build your docs in additional formats such as PDF and ePub +# formats: +# - pdf +# - epub + +# Optional but recommended, declare the Python requirements required +# to build your documentation +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +python: + install: + - requirements: docs/requirements.txt \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..d6824df4 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,74 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'viASP' +copyright = '2023, Stephan Zwicknagl, Luis Glaser' +author = 'Stephan Zwicknagl, Luis Glaser' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'nbsphinx', + 'sphinx_rtd_theme', + # 'sphinx.ext.autodoc', + 'sphinx.ext.napoleon', + 'sphinx.ext.autosectionlabel', + 'sphinx.ext.intersphinx' +] +# intersphinx_mapping = {'clorm': ('https://clorm.readthedocs.io/en/latest/', None)} + +# napoleon_google_docstring = False +# napoleon_use_ivar = True +napoleon_include_init_with_doc = False +napoleon_use_admonition_for_examples = False +napoleon_use_admonition_for_references = True + +# napoleon_use_param = True +# napoleon_type_aliases = { +# "Factbase": "clingraph.orm.Factbase", +# "dict-like": ":term:`array-like`", +# } + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +html_theme_options = { + 'canonical_url': '', +# 'analytics_id': 'UA-XXXXXXX-1', # Provided by Google in your dashboard + 'logo_only': False, + 'display_version': True, + 'display_version': True, + 'prev_next_buttons_location': 'bottom', + 'style_external_links': False, + # Toc options + 'collapse_navigation': True, + 'sticky_navigation': False, + 'navigation_depth': 4, + 'includehidden': True, + 'titles_only': False +} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +# html_static_path = ['_static'] \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..ceea33c5 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,33 @@ +======================================= +viASP: An interactive ASP visualizer +======================================= + +viASP generates interactive explanations of ASP programs and their stable models. A step-by-step break-down shows how the atoms of the stable models are derived. + +To use viASP the programs have to executed them using the clingo python API. + +.. + comment viASP uses the clingo python API, a Flask server and a Dash frontend to generate the visualizations. + +.. image:: ./img/header.png + +viASP allows you to explore the visualization in a variety of ways: + +* Inspect iterations of recursive rules individually +* Explain the derivation of symbols with arrows +* Relax the constraints of unsatisfiable programs +* Toggle parts of the program +* Show the added symbols or all of them +* Inspect a single model +* Add #show statements on the fly +* Search models, signatures and rules. + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + viasp/installation + viasp/usage + viasp/api + viasp/contributing diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..32bb2452 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..8d2834e7 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,5 @@ +clingo>=5.5.2 +sphinx>=4.5.0 +sphinx-rtd-theme==0.5.2 +nbsphinx>=0.8.8 +jinja2>=3.0.3 \ No newline at end of file diff --git a/docs/viasp/api.rst b/docs/viasp/api.rst new file mode 100644 index 00000000..455d71c3 --- /dev/null +++ b/docs/viasp/api.rst @@ -0,0 +1,4 @@ +================= +API Documentation +================= + diff --git a/docs/viasp/contributing.rst b/docs/viasp/contributing.rst new file mode 100644 index 00000000..0555e8f5 --- /dev/null +++ b/docs/viasp/contributing.rst @@ -0,0 +1,35 @@ +================= +Contributing +================= + +Requirements +============ + +- `Git `_ +- `Node.JS `_ +- `Python `_ +- A suitable browser + + +Getting started +=============== + +1. Clone the repository using :code:`git clone https://github.com/stephanzwicknagl/viasp.git` +2. Create and activate a conda environment +3. Install pip :code:`conda install pip` +4. Install viASP in editable mode :code:`pip install -e viasp -e viasp/backend -e viasp/frontend` + +Developing the backend +====================== + +1. Simply edit the code in the backend folder :code:`viasp/backend/src` +2. Run viASP with a clingo program :code:`viasp encoding.lp` + +Developing the frontend +======================= + +1. Move to frontend folder :code:`cd viasp/frontend` +2. Run :code:`npm i` to install all needed dependencies +3. Run :code:`npx webpack` to pack the javascript +4. Run viASP with a clingo program :code:`viasp encoding.lp` + diff --git a/docs/viasp/installation.rst b/docs/viasp/installation.rst new file mode 100644 index 00000000..6c96ce04 --- /dev/null +++ b/docs/viasp/installation.rst @@ -0,0 +1,40 @@ +============ +Installation +============ + +Installing with pip +=================== + +The python viasp package can be found `here `_. + +.. warning:: + The latest version is currently not available on PyPI. Please install from source. + +.. code-block:: bash + + $ pip install viasp + + +Installing from source +====================== + +The project can currently only be installed from source. To do so, clone the repository at https://github.com/stephanzwicknagl/viasp and run the following commands in the root directory of the project: + +1. create a virtual environment + +.. code-block:: bash + + $ conda create -n viasp_env + $ conda activate viasp_env + +2. install pip + +.. code-block:: bash + + $ conda install pip + +3. use pip to install the project + +.. code-block:: bash + + $ pip install -q viasp viasp/backend viasp/frontend diff --git a/docs/viasp/usage.rst b/docs/viasp/usage.rst new file mode 100644 index 00000000..0b841931 --- /dev/null +++ b/docs/viasp/usage.rst @@ -0,0 +1,105 @@ +===== +Usage +===== + +viASP consists of two parts, its frontend Dash component and the backend Flask server. Both need to be started and intialized on the local machine before each use. + +There are multiple ways of quickly starting viASP, which simplify the startup and initialization processes. + + +Command-line functionality +========================== + +.. warning:: + this is currently a planned feature + +viASP can be used from the command line. Simply run + +.. code-block:: bash + + $ viasp encoding.lp + +You can now inspect them using viASP at http://127.0.0.1:8050/. + + +Quickstart script +================= + +Run the script at ``example/quickstart.py`` to start viASP with a given encoding. + +.. code-block:: bash + + $ python quickstart.py encoding.lp + + +Extending arbitrary python scripts +================================== + +To use viASP in your own python scripts using the clingo API, you can use the following code snippets: + +To start the viASP server, use the following code: + +.. code-block:: python + + from viasp.server import startup + app = startup.run() + +Replace the ``clingo.Control`` object with the ``viasp.Control`` proxy object: + +.. code-block:: python + + from viasp import Control + options = ['0'] + ctl = Control(options) + +The Control proxy behaves exactly like the clingo Control object, but additionally provides some viASP-specific methods. + +Mark stable models for visualization: + +.. code-block:: python + + with ctl.solve(yield_=True) as handle: + for m in handle: + ctl.viasp.mark(m) + +Start the graph generation: + +.. code-block:: python + + ctl.viasp.show() + +Run the Dash app: + +.. code-block:: python + + app.run() + + +Example +------- + +In this example, all of these snippets are combined into a script using the viASP Control proxy and the clingo Application + +.. code-block:: python + + from clingo.application import clingo_main, Application + from viasp import Control + + class App(Application): + + def main(self, ctl, files): + ctl = Control(control=ctl, files=files) + + for path in files: + ctl.load(path) + ctl.ground([("base", [])]) + with ctl.solve(yield_=True) as handle: + for m in handle: + ctl.viasp.mark(m) + print(handle.get()) + ctl.viasp.show() + + + if __name__ == "__main__": + clingo_main(App(), ['0', 'encoding.lp']) + app.run() \ No newline at end of file