fix(docs): cleanup docs and addition of more installation instructions

Signed-off-by: Morten B. Rasmussen <m.rasmussen@samsung.com>

docs/source/index.rst

@@ -1,5 +1,9 @@
 .. _sec-welcome:
 
+
+
+
+
 Welcome to NVMe-Spex's documentation!
 =====================================
 
@@ -13,33 +17,86 @@ Welcome to NVMe-Spex's documentation!
    user_guide/using_spex.rst
    user_guide/dev.rst
 
+Welcome to the documentation for **Spex**, a tool for linting and extracting
+information on data structures in the NVMe specification documents.
+
+To learn more about what **Spex** does, see :ref:`sec-what-is-spex`.
+For an in-depth guide on setting up **Spex** on your system, see
+:ref:`sec-setup`.
+
+NVMe-Spex combines two tools in one package: a command-line tool that runs
+directly against NVMe specifications in DOCX format and a web application that
+runs the command-line tool in the background. The web application focuses on
+linting the documentation and presenting a report that can assist in editing the
+specifications.
+
+Getting started
+~~~~~~~~~~~~~~~
+
+You can use nvme-spex by running it as a Docker container. For setting up Docker
+on Windows, refer to the guides from `Podman
+<https://podman.io/docs/installation>`_ or `Docker Desktop
+<https://docs.docker.com/desktop/install/windows-install/>`_. On Linux, refer
+to the guide for "`Install Docker Engine <https://docs.docker.com/engine/install/>`_".
+
+
+Run with Podman
+^^^^^^^^^^^^^^^
+To start the web application, enter the following Podman command into your
+terminal (or PowerShell on Windows). This will start a Docker container running
+the web application, making port 8000 accessible on your host system.
+
+.. code-block:: shell
+
+      podman run --rm -p 8000:8000 ghcr.io/samsungds/nvme-spex-webserver:latest webserver
 
-Welcome to the documentation for **Spex**, a tool for extracting information
-on data-structures in the NVMe specification documents.
+For direct usage of the Spex command-line tool, use the following example command:
 
-To read more about what **Spex** does, see :ref:`sec-what-is-spex`.
-For help on setting up **Spex** on your system, see :ref:`sec-setup`.
+.. code-block:: shell
+
+      podman run --rm -v ~/Documents/specs/:/specs ghcr.io/samsungds/nvme-spex-webserver:latest run -s --output=/specs/output /specs/nvme_base.docx 
 
+This command works by mapping a directory on your host machine into the
+container. Ensure that the relevant specifications are present in this directory
+(e.g., ``~/Documents/specs/`` on Linux or something like ``C:/Users/Username/Documents``
+on Windows). The output of the run will be available at ``~/Documents/specs/output``
+in this example.
 
-For direct usage of nvme-spex it is possible to run it from docker. For setup of
-docker on windows we refer to guides from `Docker Desktop
-<https://docs.docker.com/desktop/install/windows-install/>`_.
+
+Run with Docker
+^^^^^^^^^^^^^^^
+For running Spex with Docker on Linux or Docker Desktop, use the equivalent
+Docker commands as shown below:
 
 .. code-block:: shell
 
       docker run --rm -v ~/Documents/specs/:/specs ghcr.io/samsungds/nvme-spex-webserver:latest run -s --output=/specs/output /specs/nvme_base.docx 
 
-The output of the run will be available at ~/Documents/specs/output in this example.
+.. code-block:: shell
 
-It is also possible to lint the docx specification by using the web application.
-To start the web application can be started with the following command:
+      docker run --rm -p 8000:8000 ghcr.io/samsungds/nvme-spex-webserver:latest webserver
+
+Installation with PIP
+^^^^^^^^^^^^^^^^^^^^^
+
+If you need to programmatically interface with Spex or prefer to run Spex
+directly on your host system, you can install NVMe-Spex using Python's pip or
+pipx tool by running the following command in a terminal:
 
 .. code-block:: shell
 
-       docker pull ghcr.io/samsungds/nvme-spex-webserver:latest
-       docker run --rm -p 8000:8000 ghcr.io/samsungds/nvme-spex-webserver:latest webserver
+      pipx install nvme-spex
+
+Ensure that Python is version 3.11 or higher. Additionally, since Python doesn't
+handle OS-level third-party dependencies, you will need to install libxml2 and
+xslt separately. You can find more information at `libxml2 <http://xmlsoft.org/>`_ and  `xlst
+<http://xmlsoft.org/XSLT/>`_.
 
-When the docker container is successfully running the web application can be
+
+Web Application
+~~~~~~~~~~~~~~~
+
+When the docker container is successfully running the web application it can be
 accessed in the browser at `http://localhost:8000 <http://localhost:8000>`_.
 
 
@@ -61,3 +118,12 @@ the following report:
 .. image:: images/web_ss_3.png
   :width: 100%
   :alt: Alternative text
+
+
+Development of Spex
+~~~~~~~~~~~~~~~~~~~
+
+For the development of Spex, the following technologies are used: Python 3.11,
+libxml2, and libxslt. The source code is available on `Github <https://github.com/SamsungDS/Spex>`_.
+
+For an in-depth guide to developing Spex, see :ref:`sec-guide-dev`.

docs/source/what_is_spex.rst

@@ -113,8 +113,3 @@ features to use.
 contained in each specification document, it is up to you to merge these
 descriptions where appropriate and to write a tool for generating code suitable
 to your project.
-
-Why does Spex *not* produce an NVMe Model?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-...