[Doc] Contributor documentation (#109)

Author: Yoric

.github/workflows/test.yml

@@ -44,6 +44,28 @@ jobs:
         path: .coverage.*
         if-no-files-found: ignore
 
+  test_doc:
+    name: Test that we can build the docs
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.10"]
+    runs-on: ${{ matrix.os }}
+    steps:
+    - name: Checkout QEK
+      uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install Hatch
+      run: |
+        pip install hatch
+    - name: Run tests
+      run: |
+        hatch -v run docs:build
+
+
   test_notebook:
     name: Run the Jupyter notebook tutorial (Unix)
     strategy:

README.md

@@ -3,7 +3,7 @@
 
 The Quantum Evolution Kernel is a Python library designed for the machine learning community to help users design quantum-driven similarity metrics for graphs and to use them inside kernel-based machine learning algorithms for graph data.
 
-The core of the library is focused on the development of a classification algorithm for molecular-graph dataset as it is presented in the published paper [Quantum feature maps for graph machine learning on a neutral atom quantum processor](https://journals.aps.org/pra/abstract/10.1103/PhysRevA.107.042615).
+The core of the library is focused on the development of a classification algorithm for molecular-graph dataset as it is presented in the published paper _Quantum feature maps for graph machine learning on a neutral atom quantum processor_([Journal Paper](https://journals.aps.org/pra/abstract/10.1103/PhysRevA.107.042615), [arXiv](https://arxiv.org/abs/2107.03247)).
 
 Users setting their first steps into quantum computing will learn how to implement the core algorithm in a few simple steps and run it using the Pasqal Neutral Atom QPU. More experienced users will find this library to provide the right environment to explore new ideas - both in terms of methodologies and data domain - while always interacting with a simple and intuitive QPU interface.
 

docs/contributing/first contact.md

@@ -0,0 +1,46 @@
+# First contact
+
+## Getting the code
+
+The code is available on GitHub.
+
+To clone it
+
+```sh
+$ git clone git@github.com:pasqal-io/quantum-evolution-kernel.git
+```
+
+or
+
+```sh
+$ git clone https://github.com/pasqal-io/quantum-evolution-kernel
+```
+
+## Hatch instructions
+
+We use `hatch` and Python 3.10 for development.
+
+### Setting up
+
+With Python and pip installed, to setup the environment:
+
+```sh
+$ pip install hatch
+$ hatch -v shell
+```
+
+This will open a shell with all the dependencies installed.
+
+### Running tests
+
+To run the unit and integration tests
+
+```sh
+$ hatch run test
+```
+
+To run linters
+
+```sh
+$ hatch run pre-commit run --all-files
+```

docs/contributing/how to contribute.md

@@ -0,0 +1,47 @@
+# How to contribute
+
+We're grateful for your interest in contributing to this library!
+
+## Asking questions
+
+If you have any question about this library, don't hesitate to ask!
+
+For more information on how to get in touch, see our [Community Portal](https://community.pasqal.com/). In particular, we have a Community Chat, it's generally the best place to ask questions.
+
+
+## Providing feedback, requesting features and filing bugs
+
+We're very interested in your feedback!
+
+The best way to request a change, whether it's an improvement, a new feature or a bugfix, is through [GitHub issues](https://github.com/pasqal-io/quantum-evolution-kernel/issues). Before filing a new issue, don't forget to search if there's already an issue on the same topic.
+
+If you're willing to help getting that issue resolved, that's even better! See the next section.
+
+
+## Opening Pull Requests
+
+We're grateful for your [Pull Requests](https://github.com/pasqal-io/quantum-evolution-kernel/pulls) (i.e. submissions) to the code, documentation, tutorials, even this document!
+
+Before your first Pull Request, you'll need to:
+
+1. [Fork](https://github.com/pasqal-io/quantum-evolution-kernel/fork) the repository;
+2. Clone your forked repository locally, either through the GitHub console, or
+```sh
+$ git clone git@github.com:YOUR_USERNAME/quantum-evolution-kernel.git
+$ cd quantum-evolution-kernel
+$ git remote add upstream https://github.com/pasqal-io/qadence.git
+```
+3. [Setup your development environment](./first%20contact.md#hatch-instructions).
+
+Before you open a Pull Request, please make sure that you have:
+
+- read the [contributor agreement](../CONTRIBUTOR%20AGREEMENT.md)
+- followed [all the testing instructions](./first%20contact.md#running-tests).
+
+
+Our testing infrastructure will check whether your changes to the code or documentation break anything. If they don't, this will start the review cycle, during which we'll discuss with you to understand the purpose of your change, fix any issue and, hopefully, get your code merged!
+
+
+## One word about patents
+
+The domain of Quantum Computing is heavily patented. If you contribute a new quantum algorithm (and not just an improvement to the library), please make sure that it's not covered by a patent!

docs/contributing/releasing.md

@@ -0,0 +1,22 @@
+# Releasing a new version
+
+You only need to read this document if you're a maintainer of this library.
+
+Steps to release a new version:
+
+1. Bump up the version number in pyproject.toml (e.g. `0.7.9`).
+2. Bump up the links in the `README.md` that point to specific versions of the documentation.
+3. Open a Pull Request.
+4. Get it merged.
+5. Optionally, test a pre-release
+    1. Open the GitHub "draft new release" panel.
+    2. Create a new tag (e.g. `v0.7.9rc1`).
+    3. Mark the release as "pre-release".
+    4. Confirm the release.
+    5. Check in the Actions that the `publish` action has succeeded.
+6. Actually release.
+    1. Open the GitHub "draft new release" panel.
+    2. Create a new tag (e.g. `v0.7.9rc1`).
+    3. Mark the release as "latest release".
+    4. Confirm the release.
+    5. Check in the Actions that the `publish` action has succeeded.

docs/index.md

@@ -3,16 +3,19 @@
 
 The Quantum Evolution Kernel is a Python library designed for the machine learning community to help users design quantum-driven similarity metrics for graphs and to use them inside kernel-based machine learning algorithms for graph data.
 
-The core of the library is focused on the development of a classification algorithm for molecular-graph dataset as it is presented in the published paper [Quantum feature maps for graph machine learning on a neutral atom quantum processor](https://journals.aps.org/pra/abstract/10.1103/PhysRevA.107.042615).
+The core of the library is focused on the development of a classification algorithm for molecular-graph dataset as it is presented in the published paper _Quantum feature maps for graph machine learning on a neutral atom quantum processor_ [^1].
+
+
+[^1]: [Quantum feature maps for graph machine learning on a neutral atom quantum processor, Boris Albrecht, Constantin Dalyac, Lucas Leclerc, Luis Ortiz-Gutiérrez, Slimane Thabet, Mauro D'Arcangelo, Julia R. K. Cline, Vincent E. Elfving, Lucas Lassablière et al.](https://journals.aps.org/pra/abstract/10.1103/PhysRevA.107.042615), [arXiv](https://arxiv.org/abs/2107.03247).
+
 
 Users setting their first steps into quantum computing will learn how to implement the core algorithm in a few simple steps and run it using the Pasqal Neutral Atom QPU. More experienced users will find this library to provide the right environment to explore new ideas - both in terms of methodologies and data domain - while always interacting with a simple and intuitive QPU interface.
 
 ## Getting started
 
-We provide several tutorials:
+You should probably start with [our Quickstart guide](./usage.md).
 
-- [tutorial 1 - Using a Quantum Device to Extract Machine-Learning Features](tutorial 1 - Using a Quantum Device to Extract Machine-Learning Features.ipynb)
-- [tutorial 2 - Machine-Learning with the Quantum EvolutionKernel](tutorial 2 - Machine-Learning with the Quantum EvolutionKernel.ipynb)
+After that, we provide [several tutorials](./tutorial%201%20-%20Using%20a%20Quantum%20Device%20to%20Extract%20Machine-Learning%20Features.ipynb).
 
 
 ## Getting in touch

mkdocs.yml

@@ -16,6 +16,11 @@ nav:
   - Open-source:
     - Licence (MIT-Derived): LICENSE.md
     - Contributor Agreement: CONTRIBUTOR AGREEMENT.md
+  - Contributing:
+    - First contact: contributing/first contact.md
+    - How to contribute: contributing/how to contribute.md
+    - Contributor Agreement: CONTRIBUTOR AGREEMENT.md
+    - Release process: contributing/releasing.md
 
 theme:
   name: material
@@ -54,6 +59,7 @@ markdown_extensions:
 - pymdownx.inlinehilite
 - pymdownx.snippets
 - pymdownx.superfences
+- footnotes
 
 plugins:
 - search

pyproject.toml

@@ -76,7 +76,7 @@ dependencies = [
 [tool.hatch.envs.default.scripts]
 before_tests = "python scripts/before_tests.py"
 test = "pytest -n auto --cov-report=term-missing --cov-config=pyproject.toml --cov=qek --cov=tests --markdown-docs {args}"
-test_readme = "pytest --markdown-docs README.md"
+test_readme = "pytest --markdown-docs README.md docs/"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]