docs: Restructure documentation

The documentation got restructured, and cards have been added with
`sphinx-design`.

Also, several fixes got issued:
- The code blocks didn't render well in the ipython notebooks, and to fix this,
  the `IPython.sphinxext.ipython_console_highlighting` is added to the
  extension list in `conf.py`.
- Building on ReadtheDocs got fixed by adding the CMake build in
  a `post_install` job.
- The original documentation URLs got modified to the new one.
- Some tutorials got updated.

.readthedocs.yaml

@@ -6,6 +6,15 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.12"
+  jobs:
+    post_install:
+      # These steps are required for building the documentation on ReadtheDocs.
+      # If Piquasso is not compiled, several modules will not be imported by the
+      # documentation, and will not appear.
+      - pip install cmake pybind11[global]
+      - cmake -B build -DCMAKE_INSTALL_PREFIX=$(pwd)
+      - cmake --build build
+      - cmake --install build
 
 sphinx:
   configuration: docs/conf.py

README.md

@@ -89,7 +89,7 @@ Resulting state: <piquasso._simulators.gaussian.state.GaussianState object at 0x
 Detected samples: [(0,), (2,), (1,), (2,), (2,), (4,), (1,), (1,), (4,), (1,)]
 ```
 
-For more details, please refer to [docs.piquasso.com](https://docs.piquasso.com/).
+For more details, please refer to [the Piquasso documentation](https://piquasso.readthedocs.io/).
 
 ## Install
 
@@ -138,7 +138,7 @@ If you are doing research using Piquasso, please cite us as follows:
 
 ## Documentation
 
-The documentation is avaliable at [docs.piquasso.com](https://docs.piquasso.com/).
+The documentation is avaliable at [https://piquasso.readthedocs.io/](https://piquasso.readthedocs.io/).
 
 ## How to contribute?
 

docs/_static/custom.css

@@ -11,4 +11,23 @@ div.nbinput.container div.input_area {
     padding: .5rem!important;
     /* border-radius: 0.5rem!important; */
     box-shadow: 0 0 7px 2px rgba(0,0,0,.1);
+}
+
+.sd-card-title {
+    font-size: 1.4em;
+    text-align: center;
+}
+
+.sd-card-text {
+    font-size: 0.8em;
+    text-align: center;
+}
+
+.mission-statement {
+    font-size: 1.3em;
+    text-align: center;
+}
+
+h1 {
+    text-align: center;
 }

docs/advanced/connectors.rst

@@ -1,25 +1,25 @@
 Connectors
-===========
+==========
 
 Alongside NumPy, Piquasso also supports TensorFlow and JAX as simulators for calculations.
 
 
 NumPy connector
-----------------
+---------------
 
 .. automodule:: piquasso._simulators.connectors.numpy_.connector
    :members:
 
 
 TensorFlow connector
----------------------
+--------------------
 
 .. automodule:: piquasso._simulators.connectors.tensorflow_.connector
    :members:
 
 
 JAX connector
---------------
+-------------
 
 .. automodule:: piquasso._simulators.connectors.jax_.connector
    :members:

docs/advanced/cvqnn.rst

@@ -1,8 +1,3 @@
-CVQNN Module
-============
-
-Some tools for simulating CVQNN (Continuous-Variable Quantum Neural Networks) are also
-available in Piquasso.
-
 .. automodule:: piquasso.cvqnn
+   :noindex:
    :members:

docs/api/computer.rst

@@ -1,5 +1,5 @@
 Computer
---------
+========
 
 .. automodule:: piquasso.api.computer
    :members:

docs/api/connector.rst

@@ -1,5 +1,5 @@
 Connector
-----------
+=========
 
 .. automodule:: piquasso.api.connector
    :members:

docs/api/exceptions.rst

@@ -1,5 +1,5 @@
 Exceptions
-----------
+==========
 
 .. automodule:: piquasso.api.exceptions
    :show-inheritance:

docs/api/index.rst

@@ -0,0 +1,18 @@
+API reference
+=============
+
+The API reference of Piquasso.
+
+.. toctree::
+   :maxdepth: 1
+
+   program
+   simulator
+   config
+   mode
+   state
+   instruction
+   result
+   exceptions
+   computer
+   connector

docs/api/instruction.rst

@@ -1,5 +1,5 @@
 Instruction
------------
+===========
 
 .. automodule:: piquasso.api.instruction
    :members:

docs/api/mode.rst

@@ -1,5 +1,5 @@
 Q
--
+=
 
 .. automodule:: piquasso.api.mode
    :members:

docs/api/program.rst

@@ -1,5 +1,5 @@
 Program
--------
+=======
 
 .. automodule:: piquasso.api.program
    :members:

docs/api/result.rst

@@ -1,5 +1,5 @@
 Result
-------
+======
 
 .. automodule:: piquasso.api.result
    :members:

docs/api/simulator.rst

@@ -1,5 +1,5 @@
 Simulator
----------
+=========
 
 .. automodule:: piquasso.api.simulator
    :show-inheritance:

docs/api/state.rst

@@ -1,5 +1,5 @@
 State
------
+=====
 
 .. automodule:: piquasso.api.state
    :members:

docs/conf.py

@@ -36,6 +36,8 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.intersphinx",
     "nbsphinx",
+    "sphinx_design",
+    "IPython.sphinxext.ipython_console_highlighting",
 ]
 
 

docs/index.rst

@@ -1,108 +1,134 @@
-Piquasso
-********
+======================
+Piquasso documentation
+======================
 
 
-Piquasso is an open source Python package, which allows you to simulate a photonic
-quantum computer. One could use Gaussian or Fock state corresponding to different
-representations to run simulations.
+|
 
+.. container:: mission-statement
 
-Installation
-============
+   Piquasso is an open source Python package, which allows you to simulate a photonic
+   quantum computer.
 
-One could easily install Piquasso with the following command:
+|
 
-.. code-block:: bash
+.. grid:: 4
 
-   pip install piquasso
+   .. grid-item-card::  Installation
+      :link: installation
+      :link-type: doc
+      :class-title: cardclass
 
-For a basic example, check out :doc:`tutorials/getting-started`.
+      Instructions on the installation of the Piquasso package
 
-One can also use Piquasso along with TensorFlow, see, e.g.,
-:doc:`tutorials/cvqnn-with-tensorflow`. To install Piquasso with TensorFlow, just enter
+   .. grid-item-card::  Tutorials
+      :link: tutorials/index
+      :link-type: doc
 
-.. code-block:: bash
+      Basic tutorials for using Piquasso
 
-   pip install piquasso[tensorflow]
+   .. grid-item-card::  Simulators
+      :link: simulators/index
+      :link-type: doc
 
+      The built-in simulators in Piquasso
 
-Similarly, Piquasso admits a JAX support, as described in :doc:`tutorials/jax-example`
-To install Piquasso with JAX is done by
+   .. grid-item-card::  API reference
+      :link: api/index
+      :link-type: doc
 
-.. code-block:: bash
+      API reference for Piquasso
 
-   pip install piquasso[jax]
 
+|
 
-.. toctree::
-   :maxdepth: 3
-   :caption: Tutorials:
-   :hidden:
+Code example
+============
 
-   tutorials/getting-started
-   tutorials/separating-programs
-   tutorials/boson-sampling
-   tutorials/gaussian-boson-sampling
-   tutorials/cvqnn-with-tensorflow
-   tutorials/jax-example
+.. code-block::
 
-.. toctree::
-   :maxdepth: 3
-   :caption: Simulators:
-   :hidden:
+   import numpy as np
+   import piquasso as pq
 
-   simulators/gaussian
-   simulators/fock
-   simulators/sampling
+   # Program definition
+   with pq.Program() as program:
+      # Prepare a Gaussian vacuum state
+      pq.Q() | pq.Vacuum()
+
+      # Displace the state on mode 0
+      pq.Q(0) | pq.Displacement(r=np.sqrt(2), phi=np.pi / 4)
+
+      # Use a beamsplitter gate on modes 0, 1
+      pq.Q(0, 1) | pq.Beamsplitter(theta=np.pi / 3, phi=np.pi / 2)
+
+      # Measurement on mode 0
+      pq.Q(0) | pq.HomodyneMeasurement(phi=0)
+
+   # Creating the Gaussian simulator
+   simulator = pq.GaussianSimulator(d=3)
+
+   # Apply the program with 10 shots
+   result = simulator.execute(program, shots=10)
+
+
+How to cite us
+==============
+
+If you are doing research using Piquasso, please cite us as follows:
+
+.. code-block::
+
+   @misc{piquasso2024,
+   title         = {Piquasso: A Photonic Quantum Computer Simulation Software Platform},
+   author        = {Z. Kolarovszki and
+                     T. Rybotycki and
+                     P. Rakyta and
+                     Á. Kaposi and
+                     B. Poór and
+                     Sz. Jóczik and
+                     D. T. R. Nagy and
+                     H. Varga and
+                     K. H. El-Safty and
+                     G. Morse and
+                     M. Oszmaniec and
+                     T. Kozsik and
+                     Z. Zimborás
+                     },
+   year          = {2024},
+   eprint        = {2403.04006},
+   archiveprefix = {arXiv},
+   primaryclass  = {quant-ph}
+   }
 
-.. toctree::
-   :maxdepth: 3
-   :caption: States:
-   :hidden:
 
-   states/gaussian
-   states/fock
-   states/sampling
 
 .. toctree::
-   :maxdepth: 3
-   :caption: Instructions:
    :hidden:
+   :caption: Basics
+
+   installation
+   tutorials/index
 
-   instructions/preparations
-   instructions/gates
-   instructions/measurements
-   instructions/channels
 
 .. toctree::
-   :maxdepth: 3
-   :caption: API:
    :hidden:
+   :caption: Features
 
-   api/program
-   api/simulator
-   api/config
-   api/mode
-   api/state
-   api/instruction
-   api/result
-   api/exceptions
-   api/computer
-   api/connector
+   simulators/index
+   states/index
+   instructions/index
 
 .. toctree::
-   :maxdepth: 3
-   :caption: Advanced:
    :hidden:
+   :caption: Advanced
 
-   advanced/cvqnn
+   api/index
    advanced/connectors
    advanced/decompositions
-
+   advanced/cvqnn
 
 .. toctree::
-   :maxdepth: 3
-   :caption: Experimental:
    :hidden:
+   :caption: Experimental
 
    experimental/fermionic