Update docs

docs/explanations.rst

@@ -9,3 +9,4 @@ Explanation of how the library works and why it works that way.
     :caption: Explanations
 
     explanations/why-is-something-so
+    explanations/why-multiprocessing

docs/explanations/why-multiprocessing.rst

@@ -0,0 +1,39 @@
+Why use Multiprocessing?
+========================
+
+The main issue with Python is working with the Global Interpreter Lock (GIL).
+This lock means Python can only run natively in a single thread, making it
+super difficult to do any CPU heavy workloads.
+
+One workaround for this would be to deploy the webapp on a cluster, such as
+Kubernetes, and have some load balancing code to spin up new instances whenever
+a call is made. 
+The easier solution, however, is to implement the Multiprocessing library. This
+allows for a new process to be spawned for a specific function call, hence 
+avoiding the GIL.
+
+For the HDF5 Reader Service, Multiprocessing has been implemented into every
+endpoint. This allows for multiple calls to be made at once without any 
+blocking.
+
+For example, in the ``/info`` endpoint, the Multiprocessing code is:
+
+.. code-block:: python
+
+    p = mp.Process(target=fetch_info, args=(path, subpath, queue))
+    p.start()
+    p.join()
+
+where ``fetch_info`` is the function containing the logic for fetching the 
+metadata. The process has to be ``start``\ed and then ``join``\ed once completed
+to prevent memory leaks.
+
+One downside of using Multiprocessing is that standard Python constructs in
+the global namespace, such as dictionaries, cannot be called from within the 
+Process. This requires using a Multiprocessing Queue object, which can have
+data ``put`` onto it in the process, and can be ``get`` from it back in the
+main process.
+
+.. code-block:: python
+
+    queue: mp.Queue = mp.Queue()

docs/tutorials.rst

@@ -9,3 +9,5 @@ Tutorials for installation, library and commandline usage. New users start here.
     :caption: Tutorials
 
     tutorials/installation
+    tutorials/querying-endpoints
+    tutorials/running-the-server

docs/tutorials/querying-endpoints.rst

@@ -0,0 +1,40 @@
+Query the HDF5 Reader Service Endpoints
+=======================================
+
+The HDF5 Reader Service provides REST endpoints for querying HDF5 files.
+
+Tree
+----
+
+The ``/tree`` endpoint returns a JSON representation of the HDF5 file tree structure.
+
+    http://0.0.0.0/8000/tree/?path=<path>
+
+Info
+----
+
+The ``/info`` endpoint returns metadata about the given node in the HDF5 file.
+
+    http://0.0.0.0/8000/info/?path=<path>&subpath=<subpath>
+
+Shapes
+------
+
+The ``/shapes`` endpoint fetches the shapes of the datasets.
+
+    http://0.0.0.0/8000/shapes/?path=<path>
+
+Search
+------
+
+The ``/search`` endpoint fetches the subnode structure of the current subnode.
+
+    http://0.0.0.0/8000/search/?path=<path>&subpath=<subpath>
+
+Slice
+-----
+
+The ``/slice`` endpoint fetches the requested slice of the given dataset.
+
+http://0.0.0.0/8000/search/?path=<path>&subpath=<subpath>&slice=0:0:0,0:0:0
+

docs/tutorials/running-the-server.rst

@@ -0,0 +1,17 @@
+Running the HDF5 Reader Service server
+======================================
+
+This tutorial shows how to run the HDF5 Reader Service server.
+
+Start the server
+----------------
+
+It is very easy to start the HDF5 reader service. All that is needed is to
+run the following command in a terminal:
+
+    $ uvicorn hdf5_reader_service.main:app
+
+However, it is also possible to run the server on a specific host or port. To
+do this, just use the ``--host`` and ``--port`` flags.
+
+    $ uvicorn hdf5_reader_service.main:app --host 127.0.0.1 --port 8000