QuTech-Delft · elenbaasc · Nov 27, 2023 · Nov 24, 2023 · Nov 24, 2023 · Nov 27, 2023
diff --git a/LICENSE → LICENSE.md b/LICENSE → LICENSE.md
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-### Mini-compiler for Quantum Inspire's quantum chip[munk]s
+# Mini-compiler for Quantum Inspire's quantum chip(munk)s
 
 ```
  ,;;:;,
@@ -11,15 +11,13 @@
           ``'"`
 ```
 
-# Installation
-
-## General installation
+## Installation
 
 ```shell
 $ pip install opensquirrel
 ```
 
-## Editable installation
+### Editable installation
 
 To perform an editable install, run the following command in the root directory of `OpenSquirrel` with the `-e` flag
 ```shell
@@ -31,23 +29,57 @@ To install the developer specific dependencies, run the command
 $ pip install -e '.[dev]'
 ```
 
-# Documentation
+## Documentation
+
+OpenSquirrel documentation is hosted through GitHub Pages [here](https://QuTech-Delft.github.io/OpenSquirrel/).
+
+### MkDocs
+
+The documentation is generated using MkDocs. For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+
+    mkdocs.yml    # The configuration file.
+    docs/
+        index.md  # The documentation homepage.
+        ...       # Other markdown pages, images and other files.
+
+#### Commands
+
+* `mkdocs new [dir-name]` - Create a new project.
+* `mkdocs serve` - Start the live-reloading docs server.
+* `mkdocs build` - Build the documentation site.
+* `mkdocs -h` - Print help message and exit.
+* `mkdocs gh-deploy` - Rebuild and deploy documentation to GitHub Pages.
+
+### Style guide
+
+We use the [Google style guide](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) for the docstring format.
+
+## Tools
 
-The package exposes only the `Circuit` class, whose up-to-date documentation is accessed:
+### Poetry
 
-- from the Python console:
-```pycon
->>> import opensquirrel
->>> help(opensquirrel.Circuit)
+Project dependencies are specified in the `pyproject.toml` file in the root directory of the project.
+
+Website: <https://python-poetry.org/>
+
+Install dependencies
+
+```shell
+$ poetry install
 ```
 
-- from a Linux shell: `python3 -c "import opensquirrel; help(opensquirrel.Circuit)"`
+Start a Poetry shell
 
-Currently there is also a set of default gates exposed as `opensquirrel.DefaultGates` to use in the `Circuit` constructor.
+```shell
+$ poetry shell
+```
+
+Within the shell PyTest and MyPy can be run accordingly:
 
-# Testing
+```shell
+$ mypy -p opensquirrel
+```
 
-To run the tests, run the following command in the root directory of `OpenSquirrel`
 ```shell
 $ pytest
 ```
diff --git a/docs/development.md b/docs/development.md
diff --git a/docs/explanation.md b/docs/explanation.md
diff --git a/docs/how-to-guides.md b/docs/how-to-guides.md
@@ -0,0 +1,2 @@
+
+The purpose of a How-to Guide is to help the user _accomplish at task_.
diff --git a/docs/index.md b/docs/index.md
@@ -1,17 +1,28 @@
-# Welcome to OpenSquirrel
+This site contains the project documentation for OpenSquirrel, _i.e._, a quantum circuit transformation and manipulation tool.
 
-## Introduction
+_<Brief intro to OpenSquirrel\>_
 
-A quantum circuit transformation and manipulation tool.
+GitHub repository: <https://github.com/QuTech-Delft/OpenSquirrel>
+
+PyPI: <https://pypi.org/project/opensquirrel/>
+
+## Table of Contents
 
-**Authors**:
+The following documentation structure is used: [Diátaxis documentation framework](https://diataxis.fr/).
+
+1. [Tutorials](tutorials.md)
+2. [How-To Guides](how-to-guides.md)
+3. [Reference](reference.md)
+4. [Explanation](explanation.md)
+
+## Authors
 
 - Pablo Le Henaff (<p.lehenaff@tudelft.nl>)
 
 - Roberto Turrado Camblor (<r.turradocamblor@tudelft.nl>)
 
 - Chris Elenbaas (<chris.elenbaas@tno.nl>)
 
-GitHub repository: <https://github.com/QuTech-Delft/OpenSquirrel>
+## Acknowledgements
 
-PyPI: <https://pypi.org/project/opensquirrel/>
+_<Who made OpenSquirrel possible?\>_
diff --git a/docs/reference.md b/docs/reference.md
@@ -0,0 +1,27 @@
+::: opensquirrel.circuit
+
+::: opensquirrel.circuit_builder
+
+::: opensquirrel.common
+
+::: opensquirrel.default_gates
+
+::: opensquirrel.gates
+
+::: opensquirrel.matrix_expander
+
+::: opensquirrel.mckay_decomposer
+
+::: opensquirrel.replacer
+
+::: opensquirrel.squirrel_ast
+
+::: opensquirrel.squirrel_ast_creator
+
+::: opensquirrel.squirrel_error_handler
+
+::: opensquirrel.test_interpreter
+
+::: opensquirrel.type_checker
+
+::: opensquirrel.writer
diff --git a/docs/tutorials.md b/docs/tutorials.md
@@ -0,0 +1 @@
+The purpose of a tutorial is to provide the user with a _successful learning experience_.
diff --git a/mkdocs.yaml b/mkdocs.yaml
@@ -1,6 +1,14 @@
 site_name: OpenSquirrel
 site_url: http://127.0.0.1:8000/
+
+theme:
+  name: "material"
+
+plugins:
+  - mkdocstrings
+
 nav:
-  - Home: index.md
-  - Development: development.md
-theme: readthedocs
+  - OpenSquirrel: index.md
+  - Tutorials: tutorials.md
+  - How-To Guides: how-to-guides.md
+  - Reference: reference.md
diff --git a/opensquirrel/__init__.py b/opensquirrel/__init__.py
@@ -1,3 +1,3 @@
-from opensquirrel.Circuit import Circuit
-from opensquirrel.CircuitBuilder import CircuitBuilder
-from opensquirrel.DefaultGates import DefaultGates
+from opensquirrel.circuit import Circuit
+from opensquirrel.circuit_builder import CircuitBuilder
+from opensquirrel.default_gates import DefaultGates
diff --git a/opensquirrel/Circuit.py → opensquirrel/circuit.py b/opensquirrel/Circuit.py → opensquirrel/circuit.py
@@ -1,15 +1,15 @@
 import antlr4
 import numpy as np
 
-from opensquirrel.DefaultGates import DefaultGates  # For the doctest.
-from opensquirrel.McKayDecomposer import McKayDecomposer
-from opensquirrel.Replacer import Replacer
-from opensquirrel.SquirrelAST import SquirrelAST
-from opensquirrel.SquirrelASTCreator import SquirrelASTCreator
-from opensquirrel.SquirrelErrorHandler import SquirrelErrorHandler
-from opensquirrel.TestInterpreter import TestInterpreter
-from opensquirrel.TypeChecker import TypeChecker
-from opensquirrel.Writer import Writer
+from opensquirrel.default_gates import DefaultGates  # For the doctest.
+from opensquirrel.mckay_decomposer import McKayDecomposer
+from opensquirrel.replacer import Replacer
+from opensquirrel.squirrel_ast import SquirrelAST
+from opensquirrel.squirrel_ast_creator import SquirrelASTCreator
+from opensquirrel.squirrel_error_handler import SquirrelErrorHandler
+from opensquirrel.test_interpreter import TestInterpreter
+from opensquirrel.type_checker import TypeChecker
+from opensquirrel.writer import Writer
 from parsing.GeneratedParsingCode import CQasm3Lexer, CQasm3Parser
 
 
@@ -18,26 +18,30 @@ class Circuit:
 
     A Circuit object is constructed from a cQasm3 string, representing a quantum circuit, and a Python dictionary
     containing the prototypes and semantic of the allowed quantum gates.
-    A default set of gates is exposed as `opensquirrel.DefaultGates` but it can be replaced and extended.
-
-    >>> c = Circuit.from_string(DefaultGates, "version 3.0; qubit[3] q; h q[0]")
-    >>> c
-    version 3.0
-    <BLANKLINE>
-    qubit[3] q
-    <BLANKLINE>
-    h q[0]
-    <BLANKLINE>
-    >>> c.decompose_mckay()
-    >>> c
-    version 3.0
-    <BLANKLINE>
-    qubit[3] q
-    <BLANKLINE>
-    x90 q[0]
-    rz q[0], 1.5707963267948966
-    x90 q[0]
-    <BLANKLINE>
+    A default set of gates is exposed as `opensquirrel.default_gates` but it can be replaced and extended.
+
+    Examples:
+        >>> c = Circuit.from_string(DefaultGates, "version 3.0; qubit[3] q; h q[0]")
+        >>> c
+        version 3.0
+        <BLANKLINE>
+        qubit[3] q
+        <BLANKLINE>
+        h q[0]
+        <BLANKLINE>
+        >>> c.decompose_mckay()
+        >>> c
+        version 3.0
+        <BLANKLINE>
+        qubit[3] q
+        <BLANKLINE>
+        x90 q[0]
+        rz q[0], 1.5707963
+        x90 q[0]
+        <BLANKLINE>
+
+    Args:
+        squirrelAST: OpenSquirrel internal AST.
     """
 
     def __init__(self, squirrelAST: SquirrelAST):
@@ -51,10 +55,10 @@ def from_string(cls, gates: dict, cqasm3_string: str):
         """Create a circuit object from a cQasm3 string. All the gates in the circuit need to be defined in
         the `gates` argument.
 
-            * type-checking is performed, eliminating qubit indices errors and incoherencies
-            * checks that used gates are supported and mentioned in `gates` with appropriate signatures
-            * does not support map or variables, and other things...
-            * for example of `gates` dictionary, please look at TestGates.py
+        * type-checking is performed, eliminating qubit indices errors and incoherencies
+        * checks that used gates are supported and mentioned in `gates` with appropriate signatures
+        * does not support map or variables, and other things...
+        * for example of `gates` dictionary, please look at TestGates.py
         """
 
         input_stream = antlr4.InputStream(cqasm3_string)

diff --git a/opensquirrel/CircuitBuilder.py → opensquirrel/circuit_builder.py b/opensquirrel/CircuitBuilder.py → opensquirrel/circuit_builder.py
@@ -1,6 +1,6 @@
-from opensquirrel.Circuit import Circuit
-from opensquirrel.DefaultGates import DefaultGates
-from opensquirrel.SquirrelAST import SquirrelAST
+from opensquirrel.circuit import Circuit
+from opensquirrel.default_gates import DefaultGates
+from opensquirrel.squirrel_ast import SquirrelAST
 
 
 class CircuitBuilder:

diff --git a/opensquirrel/Common.py → opensquirrel/common.py b/opensquirrel/Common.py → opensquirrel/common.py
diff --git a/opensquirrel/DefaultGates.py → opensquirrel/default_gates.py b/opensquirrel/DefaultGates.py → opensquirrel/default_gates.py
@@ -3,8 +3,8 @@
 
 import numpy as np
 
-from opensquirrel.Common import ArgType
-from opensquirrel.Gates import MultiQubitMatrixSemantic, SingleQubitAxisAngleSemantic
+from opensquirrel.common import ArgType
+from opensquirrel.gates import MultiQubitMatrixSemantic, SingleQubitAxisAngleSemantic
 
 DefaultGates = {
     "h": {

diff --git a/opensquirrel/Gates.py → opensquirrel/gates.py b/opensquirrel/Gates.py → opensquirrel/gates.py
@@ -2,7 +2,7 @@
 
 import numpy as np
 
-from opensquirrel.Common import ArgType
+from opensquirrel.common import ArgType
 
 
 class Semantic:

diff --git a/opensquirrel/MatrixExpander.py → opensquirrel/matrix_expander.py b/opensquirrel/MatrixExpander.py → opensquirrel/matrix_expander.py
@@ -1,7 +1,7 @@
 import numpy as np
 
-from opensquirrel.Common import Can1
-from opensquirrel.Gates import MultiQubitMatrixSemantic, Semantic, SingleQubitAxisAngleSemantic
+from opensquirrel.common import Can1
+from opensquirrel.gates import MultiQubitMatrixSemantic, Semantic, SingleQubitAxisAngleSemantic
 
 
 # This should only be used for testing and on circuits with low number of qubits.

diff --git a/opensquirrel/McKayDecomposer.py → opensquirrel/mckay_decomposer.py b/opensquirrel/McKayDecomposer.py → opensquirrel/mckay_decomposer.py
@@ -3,9 +3,9 @@
 
 import numpy as np
 
-from opensquirrel.Common import ATOL, ArgType
-from opensquirrel.Gates import SingleQubitAxisAngleSemantic, queryEntry, querySemantic, querySignature
-from opensquirrel.SquirrelAST import SquirrelAST
+from opensquirrel.common import ATOL, ArgType
+from opensquirrel.gates import SingleQubitAxisAngleSemantic, queryEntry, querySemantic, querySignature
+from opensquirrel.squirrel_ast import SquirrelAST
 
 
 def normalizeAngle(x: float) -> float:

diff --git a/opensquirrel/Replacer.py → opensquirrel/replacer.py b/opensquirrel/Replacer.py → opensquirrel/replacer.py
@@ -1,6 +1,6 @@
-from opensquirrel.Common import ArgType
-from opensquirrel.Gates import querySignature
-from opensquirrel.SquirrelAST import SquirrelAST
+from opensquirrel.common import ArgType
+from opensquirrel.gates import querySignature
+from opensquirrel.squirrel_ast import SquirrelAST
 
 
 class Replacer:
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@

		The purpose of a How-to Guide is to help the user _accomplish at task_.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		The purpose of a tutorial is to provide the user with a _successful learning experience_.