Repo initialisation from template.

README.md

@@ -1,2 +1,116 @@
-# qadence-libs
-A collection of libraries to enhance Qadence functionalities.
+# Template Python project
+
+This is a template Python project which can be used to bootstrap a new library in the Pasqal quantum software codebase.
+
+## Development tools
+
+The library uses the following tools:
+
+* [hatch](https://hatch.pypa.io/latest/) for managing virtual environment and dependencies
+* [pytest](https://docs.pytest.org/en/7.2.x/contents.html) for building the unit tests suite
+* [black](https://black.readthedocs.io/en/stable/), [isort](https://pycqa.github.io/isort/) and [flake8](https://flake8.pycqa.org/en/latest/) for code formatting and linting
+* [mypy](https://mypy.readthedocs.io/en/stable/) for static type checking
+* [pre-commit](https://pre-commit.com/) for applying linting and formatting automatically before committing new code
+
+We recommend to use [`pyenv`](https://github.com/pyenv/pyenv) for managing
+python versions for managing python versions both globally and locally:
+```bash
+# System-wide install of a python version.
+pyenv install 3.10
+
+# Use 3.10 everywhere.
+pyenv global 3.10
+
+# Or locally in the current directory.
+pyenv local 3.10
+```
+
+
+## Install from registry
+
+Before you can install the library from the private Pasqal PyPi, make sure to ask for `PYPI_USERNAME` and `PYPI_PASSWORD` on the relevant Slack channel.
+You can then set the credentials as environment variables via:
+
+```bash
+export PYPI_USERNAME=MYUSERNAME
+export PYPI_PASSWORD=THEPASSWORD
+```
+
+You are then able to install the latest version of `template-python-project` from the Pasqal private PyPi.
+
+
+## Install from source
+
+All Pasqal quantum libraries require Python >=3.8. For development, the preferred method to install this package is
+to use `hatch`. You can install from source by cloning this repository and run:
+
+```bash
+python -m pip install hatch
+python -m hatch -v shell
+
+# execute any script using the library
+python my_script.py
+```
+
+Alternatively, you can also:
+
+* install with `pip` in development mode by simply running `pip install -e .`. Notice that in this way
+  you will install all the dependencies, including extras.
+* install it with `conda` by simply using `pip` inside the Conda environment.
+
+
+## Develop
+
+When developing the package, the recommended way is to create a virtual environment with `hatch` as shown above:
+
+```bash
+python -m pip install hatch
+python -m hatch -v shell
+```
+
+When inside the shell with development dependencies, install first the pre-commit hook:
+```
+pre-commit install
+```
+
+In this way, you will get automatic linting and formatting every time you commit new code. Do not
+forget to run the unit test suite by simply running the `pytest` command.
+
+If you do not want to get into the Hatch shell, you can alternatively do the following:
+
+```bash
+python -m pip install hatch
+python -m hatch -v shell
+
+# install the pre-commit
+python -m hatch run pre-commit install
+
+# commit some code
+python -m hatch run git commit -m "My awesome commit"
+
+# run the unit tests suite
+python -m hatch run pytest
+
+```
+
+## Document
+
+You can improve the documentation of the package by editing this file for the landing page or adding new
+markdown or Jupyter notebooks to the `docs/` folder in the root of the project. In order to modify the
+table of contents, edit the `mkdocs.yml` file in the root of the project.
+
+In order to build and serve the documentation locally, you can use `hatch` with the right environment:
+
+```bash
+python -m hatch -v run docs:build
+python -m hatch -v run docs:serve
+```
+
+If you don't want to use `hatch`, just check into your favorite virtual environment and
+execute the following commands:
+
+```bash
+python -m pip install -r docs/requirements.txt
+mkdocs build
+mkdocs serve
+```

docs/css/mkdocstrings.css

@@ -0,0 +1,11 @@
+/* Indentation. */
+div.doc-contents:not(.first) {
+    padding-left: 25px;
+    border-left: 4px solid rgba(230, 230, 230);
+    margin-bottom: 80px;
+  }
+
+/* Avoid breaking parameters name, etc. in table cells. */
+td code {
+    word-break: normal !important;
+}

docs/index.md

@@ -0,0 +1,116 @@
+# Template Python project
+
+This is a template Python project which can be used to bootstrap a new library in the Pasqal quantum software codebase.
+
+## Development tools
+
+The library uses the following tools:
+
+* [hatch](https://hatch.pypa.io/latest/) for managing virtual environment and dependencies
+* [pytest](https://docs.pytest.org/en/7.2.x/contents.html) for building the unit tests suite
+* [black](https://black.readthedocs.io/en/stable/), [isort](https://pycqa.github.io/isort/) and [flake8](https://flake8.pycqa.org/en/latest/) for code formatting and linting
+* [mypy](https://mypy.readthedocs.io/en/stable/) for static type checking
+* [pre-commit](https://pre-commit.com/) for applying linting and formatting automatically before committing new code
+
+We recommend to use [`pyenv`](https://github.com/pyenv/pyenv) for managing
+python versions for managing python versions both globally and locally:
+```bash
+# System-wide install of a python version.
+pyenv install 3.10
+
+# Use 3.10 everywhere.
+pyenv global 3.10
+
+# Or locally in the current directory.
+pyenv local 3.10
+```
+
+
+## Install from registry
+
+Before you can install the library from the private Pasqal PyPi, make sure to ask for `PYPI_USERNAME` and `PYPI_PASSWORD` on the relevant Slack channel.
+You can then set the credentials as environment variables via:
+
+```bash
+export PYPI_USERNAME=MYUSERNAME
+export PYPI_PASSWORD=THEPASSWORD
+```
+
+You are then able to install the latest version of `template-python-project` from the Pasqal private PyPi.
+
+
+## Install from source
+
+All Pasqal quantum libraries require Python >=3.8. For development, the preferred method to install this package is
+to use `hatch`. You can install from source by cloning this repository and run:
+
+```bash
+python -m pip install hatch
+python -m hatch -v shell
+
+# execute any script using the library
+python my_script.py
+```
+
+Alternatively, you can also:
+
+* install with `pip` in development mode by simply running `pip install -e .`. Notice that in this way
+  you will install all the dependencies, including extras.
+* install it with `conda` by simply using `pip` inside the Conda environment.
+
+
+## Develop
+
+When developing the package, the recommended way is to create a virtual environment with `hatch` as shown above:
+
+```bash
+python -m pip install hatch
+python -m hatch -v shell
+```
+
+When inside the shell with development dependencies, install first the pre-commit hook:
+```
+pre-commit install
+```
+
+In this way, you will get automatic linting and formatting every time you commit new code. Do not
+forget to run the unit test suite by simply running the `pytest` command.
+
+If you do not want to get into the Hatch shell, you can alternatively do the following:
+
+```bash
+python -m pip install hatch
+python -m hatch -v shell
+
+# install the pre-commit
+python -m hatch run pre-commit install
+
+# commit some code
+python -m hatch run git commit -m "My awesome commit"
+
+# run the unit tests suite
+python -m hatch run pytest
+
+```
+
+## Document
+
+You can improve the documentation of the package by editing this file for the landing page or adding new
+markdown or Jupyter notebooks to the `docs/` folder in the root of the project. In order to modify the
+table of contents, edit the `mkdocs.yml` file in the root of the project.
+
+In order to build and serve the documentation locally, you can use `hatch` with the right environment:
+
+```bash
+python -m hatch -v run docs:build
+python -m hatch -v run docs:serve
+```
+
+If you don't want to use `hatch`, just check into your favorite virtual environment and
+execute the following commands:
+
+```bash
+python -m pip install -r docs/requirements.txt
+mkdocs build
+mkdocs serve
+```

docs/javascripts/mathjax.js

@@ -0,0 +1,16 @@
+window.MathJax = {
+    tex: {
+        inlineMath: [["\\(", "\\)"]],
+        displayMath: [["\\[", "\\]"]],
+        processEscapes: true,
+        processEnvironments: true
+    },
+    options: {
+        ignoreHtmlClass: ".*|",
+        processHtmlClass: "arithmatex"
+    }
+};
+
+document$.subscribe(() => {
+    MathJax.typesetPromise()
+})

docs/requirements.txt

@@ -0,0 +1,7 @@
+mkdocs-material
+mkdocstrings
+mkdocstrings-python
+mkdocs-section-index
+mkdocs-jupyter
+mkdocs-exclude
+markdown-exec

docs/sample_page.md

@@ -0,0 +1,8 @@
+This is just a sample notebook to showcase the rendering of Jupyter notebooks in the documentation.
+
+```python exec="on" source="material-block" session="main"
+from template_python.main import main
+
+msg = main()
+print(msg)
+```

mkdocs.yml

@@ -0,0 +1,79 @@
+site_name: Template Python project
+repo_url: "https://gitlab.pasqal.com/pqs/template-python-project"
+repo_name: "template_python_project"
+
+nav:
+  - Overview: index.md
+  - Sample page: sample_page.md
+
+theme:
+  name: material
+  features:
+  - content.code.annotate
+  - content.action.view
+  - content.action.edit
+  - navigation.tabs
+  - navigation.indexes
+  - navigation.sections
+  - content.code.copy
+
+  palette:
+  - media: "(prefers-color-scheme: light)"
+    scheme: default
+    primary: light green
+    accent: purple
+    toggle:
+      icon: material/weather-sunny
+      name: Switch to dark mode
+  - media: "(prefers-color-scheme: dark)"
+    scheme: slate
+    primary: black
+    accent: light green
+    toggle:
+      icon: material/weather-night
+      name: Switch to light mode
+
+markdown_extensions:
+- admonition  # for notes
+- pymdownx.arithmatex: # for mathjax
+    generic: true
+- pymdownx.highlight:
+    anchor_linenums: true
+- pymdownx.inlinehilite
+- pymdownx.snippets
+- pymdownx.superfences
+
+plugins:
+- search
+- section-index
+- markdown-exec
+- mkdocstrings:
+    default_handler: python
+    handlers:
+      python:
+        selection:
+          filters:
+            - "!^_"  # exlude all members starting with _
+            - "^__init__$"  # but always include __init__ modules and methods
+        options:
+          show_root_toc_entry: false
+          heading_level: 3
+          merge_init_into_class: true
+          docstring_section_style: spacy
+
+watch:
+  - template_python
+
+extra:
+ version:
+   provider: mike
+
+# To get nice tabs
+extra_css:
+- css/mkdocstrings.css
+
+# For mathjax
+extra_javascript:
+  - javascripts/mathjax.js
+  - https://polyfill.io/v3/polyfill.min.js?features=es6
+  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js