Update documentation. Fix broken internal links when building the documentation.

Author: dieriver

docs/ConfNodes.rst

@@ -5,7 +5,7 @@ SimulaQron uses two configuration files:
 
 * ``simulaqron_network.json`` — defines nodes, their socket ports, and network topology (described on this page)
 * ``simulaqron_settings.json`` — configures the simulation backend, timeouts, and other settings
-  (see the Settings section in `Getting Started <GettingStarted.rst>`_)
+  (see the Settings section in :ref:`Configuring Settings <settings>`)
 
 -------------------------------------
 Running all nodes on a single machine
@@ -57,7 +57,7 @@ Each example in ``examples/new-sdk/`` and ``examples/nativeMode/`` includes a ``
 the SimulaQron backend and launches the node programs. This is the easiest way to try an example::
 
     cd examples/new-sdk/corrRNG
-    sh run.sh
+    bash run.sh
 
 The ``run.sh`` script reads the ``simulaqron_network.json`` and ``simulaqron_settings.json`` in the example
 directory, so each example is self-contained.
@@ -229,7 +229,7 @@ SimulaQron can automatically generate certain well-known network topologies:
   :math:`n(n-1)/2` for :math:`n` nodes.
 
 .. note:: Topology generation via the CLI is planned but not yet implemented. For now, specify topologies
-    directly in the ``simulaqron_network.json`` file (see `Network topologies`_ below).
+    directly in the ``simulaqron_network.json`` file (see `Network topologies`_ above).
 
 Along with setting up the network with the specified topology a .png figure is also generated and stored as
 config/topology.png. This is useful if a random network is used, to easily visualize the network used.
@@ -259,5 +259,5 @@ To stop a specific network::
 .. note:: By default the network name is "default". To have multiple networks running at the same time the
     nodes cannot use the same port numbers.
 
-The JSON configuration file can hold more than one network configuration. See `Configuring the network`_ above for
-an example with multiple networks.
+The JSON configuration file can hold more than one network configuration. See `Writing the JSON config manually`_
+above for an example with multiple networks.

docs/Examples.rst

@@ -1,5 +1,5 @@
 SimulaQron Programming Examples
-================================
+===============================
 
 SimulaQron offers three ways to write quantum network programs, from highest-level to lowest-level:
 
@@ -17,38 +17,57 @@ SimulaQron offers three ways to write quantum network programs, from highest-lev
    directly to SimulaQron's virtual quantum nodes.  This is Python-specific and more verbose,
    but gives full control over the simulation backend.
 
-The examples below assume that you have already made your way through `Getting Started <GettingStarted.rst>`_:
-you have the virtual node servers up and running.
+.. _get-examples:
+
+-----------------------
+How to get the examples
+-----------------------
+
+The code of the examples can be found in `SimulaQron GitHub repository <https://github.com/SoftwareQuTech/SimulaQron>`_.
+Clone this repository using ``git``::
+
+    git clone https://github.com/SoftwareQuTech/SimulaQron.git
+
+All the examples can be found in the ``examples`` folder.
+
+When running one of the examples mentioned below, we assume that you have already made your way through
+:doc:`Getting Started <GettingStarted>` and you have the virtual node servers up and running.
+
+.. _new-sdk-examples:
 
 -----------------
 New SDK examples
 -----------------
 
-* `Overview <new-sdk/Overview.rst>`_ — Key concepts: ``NetQASMConnection``, ``EPRSocket``, ``flush()``, file structure
-* `Template <new-sdk/Template.rst>`_ — Getting started: single-node and client-server templates
-* `CorrRNG <new-sdk/CorrRNG.rst>`_ — EPR pairs between two nodes, correlated measurement
-* `Teleport <new-sdk/Teleport.rst>`_ — Quantum teleportation with classical correction messages
-* `ExtendGHZ <new-sdk/ExtendGHZ.rst>`_ — Three-party entanglement, multiple EPR sockets
-* `MidCircuitLogic <new-sdk/MidCircuitLogic.rst>`_ — Multiple ``flush()`` calls for mid-circuit classical decisions
+* :doc:`Overview <new-sdk/Overview>` — Key concepts: ``NetQASMConnection``, ``EPRSocket``, ``flush()``, file structure
+* :doc:`Template <new-sdk/Template>` — Getting started: single-node and client-server templates
+* :doc:`CorrRNG <new-sdk/CorrRNG>` — EPR pairs between two nodes, correlated measurement
+* :doc:`Teleport <new-sdk/Teleport>` — Quantum teleportation with classical correction messages
+* :doc:`ExtendGHZ <new-sdk/ExtendGHZ>` — Three-party entanglement, multiple EPR sockets
+* :doc:`MidCircuitLogic <new-sdk/MidCircuitLogic>` — Multiple ``flush()`` calls for mid-circuit classical decisions
+
+.. _event-based-examples:
 
 ---------------------
 Event-based examples
 ---------------------
 
-* `Overview <event-based/Overview.rst>`_ — Event-based programming model and state machines
-* `PingPong <event-based/PingPong.rst>`_ — Classical ping-pong between two nodes
-* `PolitePingPong <event-based/PolitePingPong.rst>`_ — State-machine message dispatch pattern
-* `QuantumCorrRNG <event-based/QuantumCorrRNG.rst>`_ — Quantum correlated RNG with state machine
-* `QuantumCorrRNGVerified <event-based/QuantumCorrRNGVerified.rst>`_ — Correlated RNG with verification protocol
+* :doc:`Overview <event-based/Overview>` — Event-based programming model and state machines
+* :doc:`PingPong <event-based/PingPong>` — Classical ping-pong between two nodes
+* :doc:`PolitePingPong <event-based/PolitePingPong>` — State-machine message dispatch pattern
+* :doc:`QuantumCorrRNG <event-based/QuantumCorrRNG>` — Quantum correlated RNG with state machine
+* :doc:`QuantumCorrRNGVerified <event-based/QuantumCorrRNGVerified>` — Correlated RNG with verification protocol
+
+.. _native-mode-examples:
 
 ---------------------
 Native mode examples
 ---------------------
 
-* `Template <native-mode/Template.rst>`_ — Template for programming in native (Twisted) mode
-* `CorrRng <native-mode/CorrRng.rst>`_ — Correlated randomness using native mode
-* `Teleport <native-mode/Teleport.rst>`_ — Teleportation using native mode
-* `GraphState <native-mode/GraphState.rst>`_ — Distributing a graph state across four nodes
+* :doc:`Template <native-mode/Template>` — Template for programming in native (Twisted) mode
+* :doc:`CorrRng <native-mode/CorrRng>` — Correlated randomness using native mode
+* :doc:`Teleport <native-mode/Teleport>` — Teleportation using native mode
+* :doc:`GraphState <native-mode/GraphState>` — Distributing a graph state across four nodes
 
 .. toctree::
     :hidden:

docs/GettingStarted.rst

@@ -21,7 +21,7 @@ you can install the *deadsnakes* repository to gain access to some specific pyth
 
     sudo add-apt-repository -y "ppa:deadsnakes/ppa"
 
-After adding the repository, you can install the *full* version of python, including the development package and the ::
+After adding the repository, you can install the *full* version of python, including the development package::
 
     sudo apt-get install python3.12-full python3.12-dev
 
@@ -56,10 +56,10 @@ Testing a simple example
 ------------------------
 
 Before delving into how to write any program yourself, let's first simply run one of the existing examples.
-Remember from the Overview that SimulaQron has two parts: the first are the virtual node servers that simulate
-the hardware at each node as well as the quantum communication between them in a transparent manner.
+Remember from the :doc:`Overview<Overview>` that SimulaQron has two parts: the first are the virtual node servers
+that simulate the hardware at each node as well as the quantum communication between them in a transparent manner.
 The second are the applications themselves which can be written in two ways: the direct way is to use the native
-mode using the Python Twisted framework connecting to the virtual node servers (see `Examples <Examples.rst>`_),
+mode using the Python Twisted framework connecting to the virtual node servers (see :ref:`Native mode examples <native-mode-examples>`),
 and the recommended way is to use the NetQASM library that calls the virtual nodes via the NetQASM interface.
 We will here illustrate how to use SimulaQron with the NetQASM library.
 
@@ -81,7 +81,7 @@ the backend of SimulaQron simply type::
     responsibility for problems caused by SimulaQron.
 
 For more information on what ``simulaqron start`` does, how to change the nodes and the ports of the network,
-the topology etc, see `Configuring the Network <ConfNodes.rst>`_.
+the topology etc, see :doc:`Configuring the Network <ConfNodes>`.
 
 To stop the backend, simply type::
 
@@ -99,7 +99,8 @@ Running a protocol
 ^^^^^^^^^^^^^^^^^^^
 
 Having started the virtual quantum nodes as above, let us now run a simple test application, which already illustrates
-some of the aspects in realizing protocols.
+some of the aspects in realizing protocols. Before proceeding, please download the SimulaQron examples as shown in the
+:ref:`How to get the examples<get-examples>` section.
 Our objective will be to realize the following protocol which will generate 1 shared random bit between Alice and Bob.
 Evidently, there would be classical means to achieve this trivial task chosen for illustration.
 
@@ -108,11 +109,12 @@ Evidently, there would be classical means to achieve this trivial task chosen fo
 
 * Both Alice and Bob measure their respective qubits to obtain a classical random number :math:`x \in \{0,1\}`.
 
-The examples can be found in ``examples/new-sdk/`` (see `Examples <Examples.rst>`_ for the full list).
-Before seeing how this example works, let us simply run the code::
+We will follow the example located in ``examples/new-sdk/coorRNG`` (see :ref:`New SDK Examples <new-sdk-examples>` for
+the full list). Before seeing how this works, let us simply run the code (assuming you're already in the ``SimulaQron``
+folder cloned from GitHub)::
 
     cd examples/new-sdk/corrRNG
-    sh run.sh
+    bash run.sh
 
 You should be seeing the following two lines::
 
@@ -125,21 +127,21 @@ going on here? Let us first look at how we will realize the example by making an
 * Alice and Bob generate one EPR pair, that is, two maximally entangled qubits :math:`A` and :math:`B` of the form
   :math:`|\Psi\rangle_{AB} = \frac{1}{\sqrt{2}} \left(|0\rangle_A |0\rangle_B + |1\rangle_A |1\rangle_B\right)`
 
-* Alice and Bob are informed of the identifiers of the qubits and are informed that entanglement was generated.
-
 * Both Alice and Bob measure their respective qubits to obtain a classical random number :math:`x \in \{0,1\}`.
 
-While the task we want to realize here is completely trivial, the addition of step 3 does however already highlight a
-range of choices on how to realize step 3 and the need to find good abstractions to allow easy application development.
-One way to realize step 3 would be to hardwire Alice's and Bob's measurements: if the hardware can identify the
+While the task we want to realize here is completely trivial, the addition of step 2 does however already highlight a
+range of choices on how to realize step 2 and the need to find good abstractions to allow easy application development.
+One way to realize step 2 would be to hardwire Alice's and Bob's measurements: if the hardware can identify the
 correct qubits from the entanglement generation, then we could instruct it to measure it immediately without asking
 for a notification from the entanglement generation process. It is clear that in a network that is a bit larger than
-our tiny three node setup, identifying the right setup requires a link between the underlying qubits and classical
+our tiny two node setup, identifying the right setup requires a link between the underlying qubits and classical
 control information: this is the objective of the classical/quantum combiner.
 
 The script ``run.sh`` executes the following two python scripts::
 
-    #!/bin/sh
+    #!/usr/bin/env bash
+
+    # Some code to start SimulaQron backend
 
     python3 aliceTest.py
     python3 bobTest.py &
@@ -188,7 +190,7 @@ Similarly the core of ``bobTest.py`` is::
     m1_val = int(m1)
     sim_conn.close()
 
-For further examples, see `Examples <Examples.rst>`_ and `The NetQASM Interface <NetQASM.rst>`_ for the full SDK reference.
+For further examples, see :doc:`Examples <Examples>` and :doc:`The NetQASM Interface <NetQASM>` for the full SDK reference.
 
 .. _settings:
 
@@ -207,7 +209,7 @@ To set a setting, for example to use the projectQ backend, type::
 This will create a file named ``simulaqron_settings.json`` in the current folder. This new file contains a full set of
 simulaqron configuration, including the setting that was just configured (using the `projectq` backend, in the example).
 
-It is also possible to manually create this` `simulaqron_settings.json`` file with any text editor::
+It is also possible to manually create this ``simulaqron_settings.json`` file with any text editor::
 
      {
         "backend": "projectq",
@@ -247,7 +249,7 @@ implement using simulaqron.
     it, set the settings and start it again.
 
 It is also possible to create the default SimulaQron network configuration in the current folder. Check the
-`Configuring the Network <ConfNodes.rst>`_ document to check how to achieve this.
+:doc:`Configuring the Network <ConfNodes>` document to check how to achieve this.
 
 ^^^^^^^^^^^^^^^^^^^
 Settings precedence
@@ -270,7 +272,7 @@ Settings Fields
 The SimulaQron settings file contains a set of fields to control the configurations of the SimulaQron simulation:
 
 * ``max_qubit``: Maximum number of qubits to simulate on the Virtual Node.
-* ``max_registers``: Maximmum number of registers to use in the Virtual Node.
+* ``max_registers``: Maximum number of registers to use in the Virtual Node.
 * ``conn_retry_time``: Number of seconds to wait between connection retries.
 * ``conn_max_retries``: Maximum number of times to retry a connection before failing the whole execution.
 * ``recv_timeout``: Maximum number of milliseconds to wait for the messages when trying to create EPR pairs.

docs/NetQASM.rst

@@ -2,16 +2,14 @@ The NetQASM interface
 =====================
 
 SimulaQron applications are written using the **NetQASM SDK**. This page describes the core concepts and
-programming model. For complete working examples, see `Examples <Examples.rst>`_.
+programming model. For complete working examples, see :doc:`Examples <Examples>`.
 
 ------------
 Installation
 ------------
 
-The NetQASM library is included as a dependency of SimulaQron. Installing SimulaQron automatically installs
-everything you need::
-
-    pip3 install simulaqron
+The NetQASM library is included as a dependency of SimulaQron. For the instructions how to install SimulaQron
+please check the :doc:`Getting Started<GettingStarted>` section.
 
 --------------
 Core concepts
@@ -94,14 +92,16 @@ You can call ``flush()`` multiple times on the same connection. This enables **m
         other_qubit.X()   # conditional correction
     conn.flush()
 
-See the mid-circuit logic example in `Examples <Examples.rst>`_ for a full demonstration.
+See the mid-circuit logic example in :doc:`Examples <Examples>` for a full demonstration.
 
 ---------------
 Minimal example
 ---------------
 
 A single-node program that creates a qubit, applies a Hadamard gate, and measures::
 
+    from netqasm.runtime.settings import set_simulator
+    set_simulator("simulaqron")
     from netqasm.sdk.external import NetQASMConnection
     from netqasm.sdk import Qubit
 
@@ -113,6 +113,9 @@ A single-node program that creates a qubit, applies a Hadamard gate, and measure
     print("Measurement outcome:", int(m))
     conn.close()
 
+If you want to run this minimal example, remember to start the SimulaQron backend before executing the code:
+``simulaqron start``.
+
 --------------------
 Two-node EPR example
 --------------------
@@ -139,7 +142,9 @@ Alice and Bob generate an EPR pair and each measure their qubit to get correlate
     print("Bob:", int(m))
     conn.close()
 
-Both sides will print the same random number (0 or 1), demonstrating quantum correlation.
+Both sides will print the same random number (0 or 1), demonstrating quantum correlation. A full working example
+of this can be found in the ``new-sdk/corrRNG`` example. See the :doc:`Correlated RNG<new-sdk/CorrRNG>` section for
+more details.
 
 -----------------------
 Classical communication
@@ -176,18 +181,19 @@ receiving classical messages::
         conn.flush()
         conn.close()
 
-See the `Template <new-sdk/Template.rst>`_ page for how to set up the client and server, and the teleportation example
-for a complete two-node program with classical messaging.
+See the :doc:`Template <new-sdk/Template>` page for how to set up the client and server, and the
+:doc:`teleportation example <new-sdk/Teleport>` for a complete two-node program with classical messaging.
 
 -----------------------
 Configuration
 -----------------------
 
 Each program needs two configuration files in its directory:
 
-* ``simulaqron_network.json`` — defines the nodes and their socket ports. See `Configuring the Network <ConfNodes.rst>`_ for details.
+* ``simulaqron_network.json`` — defines the nodes and their socket ports. See :doc:`Configuring the Network <ConfNodes>`
+  for details.
 * ``simulaqron_settings.json`` — configures the simulation backend and other settings. See the
-  Settings section in `Getting Started <GettingStarted.rst>`_.
+  Settings section in :doc:`Getting Started <GettingStarted>`.
 
 The ``stabilizer`` backend is used by default and is recommended unless you need non-Clifford gates (use
 ``qutip`` in that case).
@@ -196,6 +202,6 @@ The ``stabilizer`` backend is used by default and is recommended unless you need
 Further reading
 -----------------------
 
-* `Examples <Examples.rst>`_ — complete working examples from simple to complex
-* `New SDK Overview <new-sdk/Overview.rst>`_ — detailed SDK concepts and file structure
+* :doc:`Examples <Examples>` — complete working examples from simple to complex
+* :doc:`New SDK Overview <new-sdk/Overview>` — detailed SDK concepts and file structure
 * `NetQASM library documentation <https://netqasm.readthedocs.io/en/latest/>`_

docs/Overview.rst

@@ -15,11 +15,11 @@ In the light of the alternate interface below it may appear inefficient to expor
 the purpose of SimulaQron is precisely to explore and play with higher layer abstractions on top of any hardware, or
 its simulated version, SimulaQron. As such it is best to think of SimulaQron as a piece of simulated hardware with its
 own native interface, which we may first abstract into a higher level command language for programming. Examples of
-how to program SimulaQron in native mode can be found in `Examples <Examples.rst>`_.
+how to program SimulaQron in native mode can be found in :doc:`Examples <Examples>`.
 
 The second way to run applications is via a higher level interface, the NetQASM interface. If you want your
 applications to later use real quantum hardware more easily instead of SimulaQron, then this is the interface to use.
-Examples of how to program using the NetQASM can be found in `The NetQASM Interface <NetQASM.rst>`_.
+Examples of how to program using the NetQASM can be found in :doc:`The NetQASM Interface <NetQASM>`.
 
 .. image:: figs/netqasm_architecture.png
     :width: 500px