diff --git a/docs/Dockerfile b/docs/Dockerfile new file mode 100644 index 000000000..4021b338c --- /dev/null +++ b/docs/Dockerfile @@ -0,0 +1,5 @@ +FROM sphinxdoc/sphinx:7.1.2 + +WORKDIR /docs +ADD requirements.txt /docs +RUN pip3 install -r requirements.txt diff --git a/docs/build.sh b/docs/build.sh index 4c2e7557a..c1892a4bc 100755 --- a/docs/build.sh +++ b/docs/build.sh @@ -1,6 +1,6 @@ #!/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")")" @@ -8,5 +8,6 @@ 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" \ No newline at end of file +docker build -t $SPHINX_IMAGE_W_REQUIREMENTS . + +docker run --rm -v $(pwd):/docs $SPHINX_IMAGE_W_REQUIREMENTS \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 927eceae6..be04fa72f 100644 --- a/docs/conf.py +++ b/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 diff --git a/docs/requirements.txt b/docs/requirements.txt index f39394169..49c54ff33 100644 --- a/docs/requirements.txt +++ b/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 diff --git a/docs/the-project/documentation.rst b/docs/the-project/documentation.rst index c96e5ca75..713ff782a 100644 --- a/docs/the-project/documentation.rst +++ b/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 `_ and on GitHub Pages: `nuwcdivnpt.github.io `_ +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 `_ 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.