From c3afab14225ec18577edb3b3232fa1c6afabf966 Mon Sep 17 00:00:00 2001 From: "Morten B. Rasmussen" Date: Thu, 17 Oct 2024 10:00:06 +0200 Subject: [PATCH] fix(docs): cleanup docs and addition of more installation instructions Signed-off-by: Morten B. Rasmussen --- docs/source/index.rst | 92 +++++++++++++++++++++++++++++++----- docs/source/what_is_spex.rst | 5 -- 2 files changed, 79 insertions(+), 18 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 4cac2f3..3d38fb4 100644 --- a/docs/source/index.rst +++ b/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 +`_ or `Docker Desktop +`_. On Linux, refer +to the guide for "`Install Docker Engine `_". + + +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 -`_. + +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 `_ and `xlst +`_. -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 `_. @@ -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 `_. + +For an in-depth guide to developing Spex, see :ref:`sec-guide-dev`. diff --git a/docs/source/what_is_spex.rst b/docs/source/what_is_spex.rst index b9e5c98..da02063 100644 --- a/docs/source/what_is_spex.rst +++ b/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? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -...