Add basic documentation (#39)

* apply basic sphinx setup

* add CONTRIBUTING.md

* add basic documentation

* adapt readme

.pre-commit-config.yaml

@@ -10,6 +10,6 @@ repos:
     -   id: flake8
         additional_dependencies: [flake8-bugbear]
 -   repo: https://github.com/psf/black
-    rev: 20.8b1
+    rev: 22.3.0
     hooks:
     -   id: black

.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: 2
+
+python:
+  version: 3
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - doc
+
+sphinx:
+  builder: html
+  configuration: docs/conf.py

README.md

@@ -1,9 +1,36 @@
-# QHACK 2021
+# masKIT: Ensemble-based gate dropouts for quantum circuits
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
 [![All Contributors](https://img.shields.io/badge/all_contributors-4-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
-submitted: Tag 1.0
+MasKIT is a framework that provides masking functionality in the context of
+parameterized quantum circuits (PQC) for PennyLane. It targets *scientists* and
+simplifies researching trainability and expressivity of circuits by enabling to
+dynamically mask gates within the circuit. The framework is designed to act as
+a drop-in replacement and therefore allows to enhance your existing PennyLane
+projects with low effort.
+
+The masking is supported on different axes, i.e. layers, wires, parameters, and
+entangling gates, for different modes, i.e. adding, removing, inverting.
+
+  The current version is still in a development stage and therefore does not cover
+  the whole functionality one might imagine for masking PQCs.
+  Please feel invited to submit your contributions and ideas.
+
+## Installation
+
+The framework can be installed via pypi:
+
+```bash
+python -m pip install maskit
+```
+
+## Contributing
+
+You love research as much as we do? Anything missing? We welcome all support,
+whether on bug reports, feature requests, code, reviews, tests, documentation,
+blog posts, and more.
+Please have a look at our [contribution guidelines](docs/CONTRIBUTING.md).
 
 ## Contributors ✨
 
@@ -26,4 +53,4 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
-This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
+This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!

docs/CONTRIBUTING.md

@@ -0,0 +1,113 @@
+<!-- 
+- Steps for creating good issues or pull requests.
+- Links to external documentation, mailing lists, or a code of conduct.
+- Community and behavioral expectations. 
+-->
+
+# Contributing to masKIT
+
+First off, thank you for considering contribution to masKIT.
+It's people like you that make great research!
+
+The following is a set of guidelines for contributing to masKIT, which is hosted in the [cirKITers Organisation](https://github.com/cirkiters) on [GitHub](https://github.com/cirKITers/masKIT). 
+These are mostly guidelines, not rules. 
+Use your best judgment, and feel free to propose changes to this document in a pull request.
+
+## How to report a bug
+
+So you have encountered a bug – that’s bad – and you have decided to report it – that’s great! 
+Now, before reporting the bug take a moment to look through [previously reported bugs](https://github.com/cirkiters/maskit/issues?q=label%3Abug) if it was reported already.
+
+- Does a report exist that provides a solution? Great, go right ahead using it and enjoy masKIT.
+- Does a report exist but is still open? 
+  If it lacks some information that you can provide, leave a comment. 
+  Reports that seem not to be worked on might also benefit from a quick comment to raise awareness. 
+  Either way, consider subscribing to the report to be notified on progress.
+- Does no report exist on the bug? 
+  Open one and provide the necessary information to look into your problem.
+  - What version of masKIT and Python are you using? 
+    Have you tried another version, and did the bug occur there as well?
+  - How can the issue be reproduced reliably? 
+    Try to strip away all parts that are not needed to reproduce the issue – the more minimal and reproducible your example, the easier it is to help you.
+  - What did you expect to see and what did you see instead?
+
+If you find a solution to the bug while coming up with an example, please open a report anyway.
+
+## How to suggest a feature or enhancement
+
+If you find yourself wishing for a feature that doesn't exist in masKIT, you are probably not alone.
+New features will provide a range of opportunities for new research, so please let us know.
+Before reporting your proposal take a moment to look through the [previously suggested features](https://github.com/cirkiters/maskit/issues?q=label%3Aenhancement) if it has already been reported.
+
+- Does a report exist but is still open? If it lacks information that you can provide, leave a comment. 
+  Reports that seem not to be worked on might also benefit from a quick comment to raise awareness.
+  Either way, consider to subscribe to the report to be notified on progress.
+- Does no report exist on the feature? 
+  Open an issue on our issues list on GitHub which describes the feature you would like to see, why you need it, and how it should work.
+  - In case there are any publications on the feature, please provide links to webpages, papers or similar resources that put your suggestion into context.
+  - Can you describe the feature as an API, algorithm or code? The better you can sketch out the feature, the easier it is to discuss and implement.
+
+## Contributing Fixes and Features
+
+So you want to actively contribute to masKIT – You. Are. Awesome! 🥳 Now, with every great contribution comes great responsibility, so here are some steps to help you leave masKIT a little better than you found it.
+
+- In case you just want to get started contributing to open source research projects, check out the [recommended first issues](https://github.com/cirkiters/maskit/contribute). 
+  These features are similar to existing features of masKIT or build on common programming principles – perfect to learn the ropes of contributing without worrying much about technical details.
+- Every contribution should have an associated issue – check out how to [suggest enhancements](#how-to-suggest-a-feature-or-enhancement) and [report bugs](#how-to-report-a-bug) to find and possibly open an issue as appropriate.
+  This allows you to get feedback before investing too much time, and shows to others that you are tackling the issue.
+
+To actually contribute to the masKIT repository, you need to open and maintain a Pull Request.
+By sticking to the masKIT quality criteria and responding to feedback on the PR.
+
+### Managing a Pull Request
+
+A Pull Request allows you to commit your changes to a copy of the masKIT repository, and request them to be merged ("pulled") into the masKIT repository.
+If you are not familiar with creating Pull Requests, check out the guides on [forks](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-forks) and [pull requests from forks](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork).
+
+When opening a Pull Request, make sure to provide the information needed to understand your proposal.
+
+- Use a title that summarises the contribution.
+  By convention, use imperative mood such as "Add new dataset".
+- In the Pull Request description, give an outline of your contribution.
+  - When the contribution consists of distinct elements, add a task list.
+    You can check off tasks as they are completed, allowing you and us to track progress.
+  - Refer to issues and other Pull Requests affected by your contribution.
+    Make sure to mark the corresponding ticket of your contribution, such as "Closes #9." (assuming your issue is #9).
+
+After opening the Pull Request, respond to feedback and make new commits as needed.
+Once you and us are happy with the contribution, it will be [squash merged](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-merges#squash-and-merge-your-pull-request-commits); so don't sweat it – we can just rewrite history to fix any errors made along the way!
+
+### Keeping Quality high
+
+Having new things is great, but they must also fit to all the rest.
+There are some formal and informal quality criteria we ask you to stick to for every contribution:
+
+- Code must be formatted to conform to the black and flake8 tools.
+  This is enforced by the repository.
+  You can locally check your code by running the tools yourself or using the preconfigured precommit hooks.
+  In most cases, black is capable of reformatting code adequately.
+
+```bash
+# use black to reformat code
+python3 -m black maskit tests
+# check for remaining code smells
+python3 -m flake8 maskit tests
+```
+
+- Code must pass all existing unittests via pytest for Python 3.7 and upwards.
+  This is enforced by the repository.
+  You can locally check your code by running the tools yourself.
+
+```bash
+# evaluate unit tests
+python3 -m pytest
+```
+
+- Code should be covered by unittests.
+  This is checked but not enforced by the repository. 
+  If you contribution is similar to an existing feature, take the latter's unittests as a template; if not, we will discuss with you how to best approach unittests.
+- Any user-facing feature should be documented.
+  The documentation is compiled using sphinx from the ./docs directory.
+  If your contribution is similar to an existing feature, take the latter's documentation as a template; if not, we will discuss with you how to best approach documentation.
+
+Phew! That was a lot to read! Now go out there and put that knowledge to good use – we are happy to help you along the way.

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)

docs/_static/custom.css

@@ -0,0 +1,3 @@
+dl {
+    margin-bottom: 15px;
+}

docs/conf.py

@@ -0,0 +1,67 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(".."))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "masKIT"
+copyright = "2021-22, Eileen Kuehn, Christof Wendenius"
+author = "Eileen Kuehn, Christof Wendenius"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ["sphinx.ext.autodoc", "myst_parser"]
+
+# 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 -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "alabaster"
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+html_theme_options = {
+    "description": "Ensembble-based gate dropouts for quantum circuits",
+    "github_user": "cirkiters",
+    "github_repo": "maskit",
+    "fixed_sidebar": True,
+    "github_banner": True,
+    "github_button": True,
+}
+
+# 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"]
+
+myst_heading_anchors = 2

docs/index.rst

@@ -0,0 +1,42 @@
+.. masKIT documentation master file, created by
+   sphinx-quickstart on Wed Sep  1 16:46:06 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Ensemble-based gate dropouts for quantum circuits
+=====================================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Usage and Guides
+   :hidden:
+
+   source/getting_started
+   source/masks
+   source/ensembles
+   source/glossary
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Development
+   :hidden:
+
+   CONTRIBUTING.md
+   source/publishing
+
+MasKIT is a framework that provides masking functionality in the context of
+parameterized quantum circuits for PennyLane.
+It simplifies researching trainability and expressivity of those circuits by
+enabling to dynamically mask gates within a circuit.
+The framework is designed to act as a drop-in replacement and therefore allows
+to enhance your existing PennyLane projects with low effort.
+
+The masking is supported on different axes, i.e. layers, wires, parameters, and
+entangling gates, for different modes, i.e. adding, removing, inverting.
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

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
+
+if "%1" == "" goto help
+
+%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.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/ensembles.rst

@@ -0,0 +1,3 @@
+===============
+Using Ensembles
+===============

docs/source/getting_started.rst

@@ -0,0 +1,19 @@
+===========
+Quick Guide
+===========
+
+Installation
+============
+
+The project is published on PyPi and can therefore be installed via pip.
+
+.. code:: bash
+    
+    python3 -m pip install maskit
+
+If you prefer to use the latest development version, you can also install the
+framework directly from GitHub.
+
+.. code:: bash
+
+    python3 -m pip install git+https://github.com/cirkiters/maskit.git

docs/source/glossary.rst

@@ -0,0 +1,3 @@
+=================
+Glossary of Terms
+=================