Let's make the doc generation work - resolves #76. (#78)

* [Doc] Use absolute links in README.md

Since README.md is copied to pypi.org, relative links won't make it.

* [Doc] Uploading the documentation is good, but generating it is fine step, too.

* [Cleanup] Move utils with other utilities

* [CI] Let's not forget to install mkapi

Author: Yoric

README.md

@@ -80,8 +80,8 @@ model.fit(X_train, y_train)
 
 We have a two parts tutorial:
 
-1. [Using a Quantum Device to extract machine-learning features](examples/tutorial%201%20-%20Using%20a%20Quantum%20Device%20to%20Extract%20Machine-Learning%20Features.ipynb);
-2. [Machine Learning with the Quantum Evolution Kernel](examples/tutorial%202%20-%20Machine-Learning%20with%20the%20Quantum%20EvolutionKernel.ipynb)
+1. [Using a Quantum Device to extract machine-learning features](https://github.com/pasqal-io/quantum-evolution-kernel/blob/main/examples/tutorial%201%20-%20Using%20a%20Quantum%20Device%20to%20Extract%20Machine-Learning%20Features.ipynb);
+2. [Machine Learning with the Quantum Evolution Kernel](https://github.com/pasqal-io/quantum-evolution-kernel/blob/main/examples/tutorial%202%20-%20Machine-Learning%20with%20the%20Quantum%20EvolutionKernel.ipynb)
 
 See also the [full API documentation](https://pasqal-io.github.io/quantum-evolution-kernel/latest/).
 

docs/LICENSE.md

@@ -0,0 +1,13 @@
+PASQAL OPEN-SOURCE SOFTWARE LICENSE AGREEMENT (MIT-derived)
+
+The author of the License is:
+  Pasqal, a Société par Actions Simplifiée (Simplified Joint Stock Company) registered under number 849 441 522 at the Registre du commerce et des sociétés (Trade and Companies Register) of Evry – France, headquartered at 24 rue Émile Baudot – 91120 – Palaiseau – France, duly represented by its Président, M. Georges-Olivier REYMOND, Hereafter referred to as « the Licensor »
+
+- Permission is hereby granted, free of charge, to any person obtaining a copy of this software (the “Licensee”) and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. The Software is “as is”, without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and non-infringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise arising from, out of or in connection with the Software or the use or other dealings in the Software.
+
+- If use of the Software leads to the necessary use of any patent of the Licensor and/or any of its Affiliates (defined as a company owned or controlled by the Licensor), the Licensee is granted a royalty-free license, in any country where such patent is in force, to use the object of such patent; or use the process covered by such patent,
+
+- Such a patent license is granted for internal research or academic use of the Licensee's, which includes use by employees and students of the Licensee, acting on behalf of the Licensee, for research purposes only.
+
+- The License is governed by the laws of France. Any dispute relating to the License, notably its execution, performance and/or termination shall be brought to, heard and tried by the Tribunal Judiciaire de Paris, regardless of the rules of jurisdiction in the matter.

docs/index.md

@@ -1,12 +1,91 @@
 # "Quantum Evolution Kernel"
 ## Installation
-Installation guidelines
+### Using `hatch`, `uv` or any pyproject-compatible Python manager
+
+Edit file `pyproject.toml` to add the line
+
+```toml
+  "quantum-evolution-kernel"
+```
+
+to the list of `dependencies`.
+
+### Using `pip` or `pipx`
+To install the `pipy` package using `pip` or `pipx`
+
+1. Create a `venv` if that's not done yet
+
+```sh
+$ python -m venv venv
+
+```
+
+2. Enter the venv
+
+```sh
+$ . venv/bin/activate
+```
+
+3. Install the package
+
+```sh
+$ pip install quantum-evolution-kernel
+# or
+$ pipx install quantum-evolution-kernel
+```
 
 ## Usage
-Usage guidelines
+
+```python
+# Load a dataset
+import torch_geometric.datasets as pyg_dataset
+og_ptcfm = pyg_dataset.TUDataset(root="dataset", name="PTC_FM")
+
+# Setup a quantum feature extractor for this dataset.
+# In this example, we'll use QutipExtractor, to emulate a Quantum Device on our machine.
+import qek.data.graphs as qek_graphs
+import qek.data.extractors as qek_extractors
+extractor = qek_extractors.QutipExtractor(compiler=qek_graphs.PTCFMCompiler())
+
+# Add the graphs, compile them and look at the results.
+extractor.add_graphs(graphs=og_ptcfm)
+extractor.compile()
+processed_dataset = extractor.run().processed_data
+
+# Prepare a machine learning pipeline with Scikit Learn.
+from sklearn.model_selection import train_test_split
+from sklearn.svm import SVC
+
+X = [data for data in processed_dataset]  # Features
+y = [data.target for data in processed_dataset]  # Targets
+X_train, X_test, y_train, y_test = train_test_split(X, y, stratify = y, test_size=0.2, random_state=42)
+
+# Train a kernel
+from qek.kernel import QuantumEvolutionKernel as QEK
+kernel = QEK(mu=0.5)
+model = SVC(kernel=kernel, random_state=42)
+model.fit(X_train, y_train)
+```
 
 ## Documentation
-Documentation guidelines
+
+::: qek
+
+## Tutorials
+
+We have a two parts tutorial:
+
+1. [Using a Quantum Device to extract machine-learning features](https://github.com/pasqal-io/quantum-evolution-kernel/blob/main/examples/tutorial%201%20-%20Using%20a%20Quantum%20Device%20to%20Extract%20Machine-Learning%20Features.ipynb);
+2. [Machine Learning with the Quantum Evolution Kernel](https://github.com/pasqal-io/quantum-evolution-kernel/blob/main/examples/tutorial%202%20-%20Machine-Learning%20with%20the%20Quantum%20EvolutionKernel.ipynb)
+
+## Getting in touch
+
+- [Pasqal Community Portal](https://community.pasqal.com/) (forums, chat, tutorials, examples, code library).
+- [GitHub Repository](https://github.com/pasqal-io/quantum-evolution-kernel) (source code, issue tracker).
+- [Professional Support](https://www.pasqal.com/contact-us/) (if you need tech support, custom licenses, a variant of this library optimized for your workload, your own QPU, remote access to a QPU, ...)
 
 ## Contribute
-Contribution guidelines
+
+The GitHub repository is open for contributions!
+
+Don't forget to read the [Contributor License Agreement]().

examples/tutorial 1 - Using a Quantum Device to Extract Machine-Learning Features.ipynb

@@ -152,13 +152,16 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "from pathlib import Path\n",
+    "\n",
+    "\n",
     "HAVE_PASQAL_ACCOUNT = False # If you have a PASQAL Cloud account, fill in the details and set this to `True`.\n",
     "\n",
     "if HAVE_PASQAL_ACCOUNT:\n",
     "    # Use the QPU Extractor.\n",
     "    extractor = qek_extractors.RemoteQPUExtractor(\n",
     "        # Once computing is complete, data will be saved in this file.\n",
-    "        path=\"saved_data.json\",\n",
+    "        path=Path(\"saved_data.json\"),\n",
     "        compiler = compiler,\n",
     "        project_id = \"XXXX\", # Replace this with your project id on the PASQAL Cloud\n",
     "        username = \"XXX\",    # Replace this with your username on PASQAL Cloud\n",
@@ -216,7 +219,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import qek.data.dataset as qek_dataset\n",
+    "import qek.data.processed_data as qek_dataset\n",
     "processed_dataset = qek_dataset.load_dataset(file_path=\"ptcfm_processed_dataset.json\")\n",
     "print(f\"Size of the quantum compatible dataset = {len(processed_dataset)}\")"
    ]

examples/tutorial 1a - Using a Quantum Device to Extract Machine-Learning Features - low-level.ipynb

@@ -186,7 +186,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from qek.data.dataset import ProcessedData\n",
+    "from qek.data.processed_data import ProcessedData\n",
     "from qek.backends import QutipBackend\n",
     "\n",
     "# In this tutorial, to make things faster, we'll only run the sequences that require 5 qubits or less.\n",
@@ -308,7 +308,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import qek.data.dataset as qek_dataset\n",
+    "import qek.data.processed_data as qek_dataset\n",
     "processed_dataset = qek_dataset.load_dataset(file_path=\"ptcfm_processed_dataset.json\")\n",
     "print(f\"Size of the quantum compatible dataset = {len(processed_dataset)}\")"
    ]
@@ -333,8 +333,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from qek.data.dataset import ProcessedData\n",
-    "\n",
     "# The geometry we compiled from this graph for execution on the Quantum Device.\n",
     "dataset_example: ProcessedData = processed_dataset[64]\n",
     "dataset_example.draw_register()"

examples/tutorial 2 - Machine-Learning with the Quantum EvolutionKernel.ipynb

@@ -61,7 +61,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import qek.data.dataset as qek_dataset\n",
+    "import qek.data.processed_data as qek_dataset\n",
     "\n",
     "# Load the dataset we processed in the quantum extraction tutorial\n",
     "processed_dataset = qek_dataset.load_dataset(file_path=\"ptcfm_processed_dataset.json\")\n",

mkdocs.yml

@@ -4,6 +4,9 @@ repo_name: "Quantum Evolution Kernel"
 
 nav:
   - Overview: index.md
+  - Reference: $api/qek.***
+  - License: LICENSE.md
+  - CLA: CONTRIBUTOR LICENSE AGREEMENT.md
 
 theme:
   name: material
@@ -46,6 +49,7 @@ plugins:
 - search
 - section-index
 - markdown-exec
+- mkapi
 - mkdocstrings:
     default_handler: python
     handlers:

pyproject.toml

@@ -102,6 +102,7 @@ dependencies = [
   "mkdocstrings-python",
   "mkdocs-section-index",
   "mkdocs-exclude",
+  "mkapi",
   "markdown-exec",
   "mike",
 ]

qek/__init__.py

@@ -0,0 +1,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).
+
+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.
+"""

qek/backends.py

@@ -1,3 +1,7 @@
+"""
+Low-level tools to execute compiled registers and pulses onto Quantum Devices, including local emulators, remote emulators and physical QPUs.
+"""
+
 import abc
 import asyncio
 from math import ceil
@@ -13,7 +17,7 @@
 
 from qek.data.extractors import deserialize_device
 from qek.shared.error import CompilationError
-from qek.utils import make_sequence
+from qek.shared._utils import make_sequence
 
 
 class BaseBackend(abc.ABC):