docs: build updates (NUWCDIVNPT#1162)

* chore: update docs dependencies

* wip

* tweaked build materials a bit

* added versions

* updates to docs build process

docs/Dockerfile

@@ -0,0 +1,5 @@
+FROM sphinxdoc/sphinx:7.1.2
+
+WORKDIR /docs
+ADD requirements.txt /docs
+RUN pip3 install -r requirements.txt

docs/build.sh

@@ -1,12 +1,13 @@
 #!/bin/bash
 
-SPHINX_IMAGE=sphinxdoc/sphinx:5.3.0
+SPHINX_IMAGE_W_REQUIREMENTS=sphinx-w-requirements
 
 # Change to this script directory
 cd "$(dirname "$(realpath "$0")")"
 
 find _build -type f -not -name '.gitignore' -delete
 find _build -type d -empty -delete
 
-docker run --rm -v $(pwd):/docs $SPHINX_IMAGE \
-  /bin/bash -c "pip3 install -r /docs/requirements.txt && make html && chown -R $(id -u):$(id -g) /docs/_build"
+docker build -t $SPHINX_IMAGE_W_REQUIREMENTS .
+
+docker run --rm -v $(pwd):/docs $SPHINX_IMAGE_W_REQUIREMENTS

docs/conf.py

@@ -34,10 +34,8 @@
     'sphinx_rtd_theme',
     'sphinxcontrib.images',
     'sphinx.ext.todo',
-    'recommonmark',
+    'myst_parser',    
     'sphinx_tabs.tabs'
-    # ,
-    # 'sphinx_markdown_tables',
 ]
 
 todo_include_todos = True

docs/requirements.txt

@@ -2,29 +2,29 @@ alabaster==0.7.12
 Babel==2.9.1
 certifi==2023.7.22
 chardet==4.0.0
-colorama==0.4.4
+colorama==0.4.5
 commonmark==0.9.1
-docutils==0.16
+docutils==0.18.1
 idna==2.10
-imagesize==1.2.0
-Jinja2==2.11.3
+imagesize==1.4.1
+Jinja2==3.1.2
 Markdown==3.3.3
-MarkupSafe==1.1.1
-packaging==20.9
+MarkupSafe==2.1.3
+packaging==23.2
 Pygments==2.15.0
 pyparsing==2.4.7
 pytz==2021.1
-recommonmark==0.7.1
 requests==2.31.0
+myst_parser==2.0.0
 snowballstemmer==2.1.0
-sphinx-rtd-theme==0.5.1
+sphinx-rtd-theme==2.0.0
 sphinxcontrib-applehelp==1.0.2
 sphinxcontrib-devhelp==1.0.2
-sphinxcontrib-htmlhelp
+sphinxcontrib-htmlhelp==2.0.4
 sphinxcontrib-images==0.9.4
 sphinxcontrib-jsmath==1.0.1
 sphinxcontrib-qthelp==1.0.3
-sphinxcontrib-serializinghtml
-sphinx-tabs
+sphinxcontrib-serializinghtml==1.1.9
+sphinx-tabs==3.4.4
 urllib3==1.26.18
 

docs/the-project/documentation.rst

@@ -5,24 +5,33 @@ Documentation
 ########################################
 
 
-The STIG Manager OSS Documentation is written in reStructuredText. Sphinx and the Read The Docs theme is used to generate the site, which is located in the project repo and hosted on Read The Docs: `stig-manager.readthedocs.io <https://stig-manager.readthedocs.io/>`_ and on GitHub Pages: `nuwcdivnpt.github.io <https://nuwcdivnpt.github.io/stig-manager/#/>`_
+The STIG Manager OSS Documentation is written in reStructuredText. Sphinx and the Read The Docs theme is used to generate the site, which is located in the project repo and hosted on Read The Docs: `stig-manager.readthedocs.io <https://stig-manager.readthedocs.io/>`_ 
 
 
 Documentation Build
 ----------------------
 
+Build with Docker
++++++++++++++++++++++
+
+#. Clone the STIG Manager repository from GitHub.
+#. Navigate to /docs folder of the repository. 
+#. Build the Docker image using the following command: ``docker build -t sphinx-w-requirements .``
+#. Run the Docker image using the following command: ``docker run --rm -v "$(pwd):/docs" sphinx-w-requirements``
+#. The build product is located in ``_build`` in the docs directory.
+
+Alternatively, you can run the ``build.sh`` script located in the /docs directory of the repository. This script will build the Docker image and run the container, generating the documentation.
+
+Build with Python
++++++++++++++++++++++
+
 To build the documentation locally:
 
 #. Clone the STIG Manager repository from GitHub.
 #. Install Python
 #. Install Sphinx ``pip install sphinx``
 #. Navigate to /docs folder of the repository. 
-#. Install the following sphinx extensions using the ``pip install`` command (listed in the extensions array of the local conf.py file):
-
-    - ``sphinx-rtd-theme``
-    - ``recommonmark``
-    - ``sphinxcontrib.images``
-
+#. Install the documentation build requirements ``pip install -r requirements.txt``
 #. Depending on the OS you are using, build the documentation using make.bat or the Makefile, and specify html as the format. Windows PowerShell example: ``./make html``
 
 By default, the build product is located in ``_build`` in the docs directory.