doc: overall improvement of the documentation display (#4)

* docs: first doc build

* chore: change the name of the lib where needed

* docs: update github links

* docs: add the first example

* docs: add the getting started

* docs: inline the footer

.readthedocs.yaml

@@ -9,7 +9,7 @@ build:
     python: "3.9"
   jobs:
     pre_build:
-      - sphinx-apidoc --force --module-first --templatedir=docs/source/_templates/apidoc -o docs/source/_api ./src
+      - sphinx-apidoc --force --module-first -o docs/source/_api ./qutree
 
 # -- conf location -------------------------------------------------------------
 sphinx:

docs/source/_static/custom.css

@@ -0,0 +1,11 @@
+/*******************************************************************************
+ *  make the footer inlined
+ */
+ .footer-item {
+    display: inline-block;
+  }
+  .footer-item:not(:last-child) {
+    border-right: 1px solid var(--pst-color-text-base);
+    margin-right: 0.5em;
+    padding-right: 0.5em;
+  }

docs/source/conf.py

@@ -14,19 +14,25 @@
 
 sys.path.insert(0, os.path.abspath("."))
 sys.path.insert(0, os.path.abspath("../.."))
+sys.path.insert(0, os.path.abspath("../../examples"))
 
-from alicelib import __author__, __version__  # noqa
+from qutree import __author__, __version__  # noqa
 
 # -- Project information -------------------------------------------------------
-project = "template"
+project = "qutree"
 copyright = f"2022-{datetime.now().year}, {__author__}"
 author = __author__
 release = __version__
 
 # -- General configuration -----------------------------------------------------
 extensions = [
     "sphinx.ext.autosummary",
-    "numpydoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "nbsphinx",
+    "sphinx_copybutton",
+    # https://github.com/spatialaudio/nbsphinx/issues/687
+    "IPython.sphinxext.ipython_console_highlighting",
 ]
 templates_path = ["_templates"]
 exclude_patterns = ["**.ipynb_checkpoints"]  # when working in a Jupyter env.
@@ -35,9 +41,33 @@
 # -- Options for HTML output ---------------------------------------------------
 html_theme = "pydata_sphinx_theme"
 html_static_path = ["_static"]
+html_css_files = ["custom.css"]
 
 # -- Options for autosummary/autodoc output ------------------------------------
 autosummary_generate = True
 autoclass_content = "class"
 
 # -- Options of the HTML theme -------------------------------------------------
+html_theme_options = {
+    "use_edit_page_button": True,
+    "show_prev_next": True,
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/alice4space/qutree",
+            "icon": "fa-brands fa-github",
+        },
+        {
+            "name": "Pypi",
+            "url": "https://pypi.org",
+            "icon": "fa-brands fa-python",
+        },
+    ],
+}
+html_context = {
+    "github_user": "alice4space",
+    "github_repo": "qutree",
+    "github_version": "main",
+    "doc_path": "docs/source",
+}
+

examples/demo.ipynb → docs/source/examples/demo.ipynb

@@ -1,5 +1,14 @@
 {
  "cells": [
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "257c99e6",
+   "metadata": {},
+   "source": [
+    "# Usage examples "
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -23,15 +32,16 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from bbt import BBT"
+    "from qutree import BBT"
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "31dac37d-1a3e-4598-bd02-266fe7d3e2a2",
    "metadata": {},
    "source": [
-    "# Bell state preparation"
+    "## Bell state preparation"
    ]
   },
   {
@@ -76,11 +86,12 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "1db6830b-2a75-4909-98cc-ca721dac2e22",
    "metadata": {},
    "source": [
-    "# Study how an encoding spans the hilbert space"
+    "## Study how an encoding spans the hilbert space"
    ]
   },
   {
@@ -126,11 +137,12 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "d67120f0-1ffa-4b7e-a6a3-786975a844fe",
    "metadata": {},
    "source": [
-    "# quantum states dataset from Machine Learning"
+    "## quantum states dataset from Machine Learning"
    ]
   },
   {
@@ -151,14 +163,15 @@
     "# read the file from data folder in github\n",
     "# mask until the repo is public\n",
     "#with tempfile.NamedTemporaryFile() as tmp:\n",
-    "#    url = 'https://raw.githubusercontent.com/alice4space/aliceLib/main/examples/data/iris_quantum_kernel.npy'\n",
+    "#    url = 'https://raw.githubusercontent.com/alice4space/qutree/main/examples/data/iris_quantum_kernel.npy'\n",
     "#    urlretrieve(url, tmp.name)\n",
     "#    states_ml = np.load(tmp.name,allow_pickle=True)\n",
     "\n",
-    "# safe from Alice local files \n",
+    "# safe from Alice local files\n",
+    "# it's hacky and should be removed as soon as the lib goes public \n",
     "from pathlib import Path \n",
     "\n",
-    "file = Path.home()/'aliceLib'/'examples'/'data'/'iris_quantum_kernel.npy'\n",
+    "file = Path(\"\").parent/\"data\"/\"iris_quantum_kernel.npy\"\n",
     "states_ml = np.load(file)"
    ]
   },
@@ -177,11 +190,12 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "518b20c9-29a4-40b0-be95-ed8bd55f7c9c",
    "metadata": {},
    "source": [
-    "# hamiltonian simulation"
+    "## hamiltonian simulation"
    ]
   },
   {
@@ -197,11 +211,12 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "3da76d1a-68a4-4922-ad0d-9e87e686239d",
    "metadata": {},
    "source": [
-    "## excite only two eigenstates : a single frequency"
+    "### excite only two eigenstates : a single frequency"
    ]
   },
   {
@@ -235,11 +250,12 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "ac6324b5-3dcc-430b-9400-379c39538d16",
    "metadata": {},
    "source": [
-    "## excite three eigenstates : three frequencies"
+    "### excite three eigenstates : three frequencies"
    ]
   },
   {
@@ -298,7 +314,12 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.9"
+   "version": "3.8.3"
+  },
+  "vscode": {
+   "interpreter": {
+    "hash": "3a8723e76c97419226acc73879efcf4e97fe0647ebdba2efabf443849b0a40f0"
+   }
   }
  },
  "nbformat": 4,

docs/source/index.rst

@@ -1,13 +1,12 @@
-.. template documentation master file, created by
-   sphinx-quickstart on Tue Jan 18 09:31:08 2022.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
 
-Welcome to the lib
-==================
+qutree
+======
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+   :hidden:
 
+   setup/index
    API <_api/modules>
+   Examples <examples/demo>
+
+Plot sets of multiqubit quantum pure states as a binary tree of Bloch spheres.

docs/source/setup/authors.rst

@@ -0,0 +1,4 @@
+authors
+=======
+
+.. include :: ../../../AUTHORS.rst

docs/source/setup/contribute.rst

@@ -0,0 +1 @@
+.. include :: ../../../CONTRIBUTING.rst

docs/source/setup/index.rst

@@ -0,0 +1,17 @@
+Getting started
+===============
+
+Overview
+--------
+Plot sets of multiqubit quantum pure states as a binary tree of Bloch spheres
+
+In this section you will find everything you need to know to use the lib.
+Examples can be found in the example section: :doc:`../examples/demo`.
+
+.. toctree::
+    :hidden:
+    :maxdepth: 2
+
+    install
+    authors
+    contribute