Adding Requirements and QA to Docs (#2076)

.github/workflows/docs.yaml

@@ -30,14 +30,30 @@ jobs:
         run: sudo apt-get -y install pandoc
       - name: Setup Graphviz
         uses: ts-graphviz/[email protected]
-      - name: Make HTML Docs
+      - name: Make html/pdf Docs
+        continue-on-error: true
         run: |
+          sudo apt-get install texlive-xetex
+          sudo apt-get install texlive-latex-base
+          sudo apt-get install texlive-fonts-recommended
+          sudo apt-get install texlive-latex-extra
+          sudo apt-get install texlive-full
           pip install -e .[memprof,mpi,test,docs]
+          python -c "from armi.bookkeeping.report.reportingUtils import getSystemInfo;print(getSystemInfo())" > system_info.log
+          date > python_details.log
+          python --version >> python_details.log
+          pip freeze >> python_details.log
+          pytest --junit-xml=test_results.xml -v -n 4 armi > pytest_verbose.log
           cd doc
           git submodule init
           git submodule update
+          echo "make html:"
           make html
-          make simplepdf
+          echo "make latex:"
+          make latex
+          cd _build/latex/
+          echo "latexmk -pdf -f -interaction=nonstopmode ARMI.tex:"
+          latexmk -pdf -f -interaction=nonstopmode ARMI.tex
       - name: Deploy
         if: github.ref == 'refs/heads/main'
         uses: JamesIves/[email protected]
@@ -58,5 +74,5 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: pdf-docs
-          path: doc/_build/simplepdf/ARMI.pdf
+          path: doc/_build/latex/ARMI.pdf
           retention-days: 5

.gitignore

@@ -5,9 +5,11 @@
 *.pyx
 
 # No build artifacts
+*.aux
 *.dll
+*.fdb_latexmk
+*.fls
 *.lib
-.apidocs/
 /bin
 armi/tests/tutorials/case-suite
 bin/*
@@ -17,6 +19,7 @@ coverage.xml
 coverage_results.*
 dist-*/
 dist/
+doc/.apidocs
 doc/_build
 doc/anl-afci-177
 doc/gallery
@@ -26,6 +29,7 @@ doc/tutorials/case-suite
 doc/user/tutorials
 htmlcov/
 monkeytype.*
+test_results.*
 wheelhouse
 
 # No workspace crumbs
@@ -60,8 +64,11 @@ armi-venv/*
 dump-temp-*
 dump-tests*
 phabricator-lint.txt
+pytest_verbose.log
 pytestdebug.log
+python_details.log
 reportsOutputFiles/
+system_info.log
 tags
 temp-*
 venv*/

doc/.static/css/theme_fixes.css

@@ -12,17 +12,28 @@
    }
 }
 
+img {
+   max-width: 100% !important;
+}
+
+/* long tables */
 .rst-content table.docutils {
     margin: 0;
     padding: 0;
     font-size: 10pt;
 }
 
-img {
-   max-width: 100% !important;
+.rst-content table.docutils td, .rst-content table.docutils th, .rst-content table.field-list td, .rst-content table.field-list th, .wy-table td, .wy-table th {
+    margin: 0;
+    padding: 1px;
+}
+
+/* code snippets */
+.rst-content .linenodiv pre, .rst-content div[class^=highlight] pre, .rst-content pre.literal-block {
+    ssp-tiny;
 }
 
-/* get eq numbers to show on the side of the equation */
+/* move equation numbers to right side of the equation */
 span.eqno {
     float: right;
 }

doc/.static/needs_templates/test.need

@@ -0,0 +1,24 @@
+{% if sequence is not none %}*Required Testing Sequence:* {{sequence}}{%endif%}
+
+{% if branching is not none %}*Logic Branches:* {{branching}}{%endif%}
+
+{% if required_inputs is not none %}*Necessary Inputs for Simulation:* {{required_inputs}}{%endif%}
+
+{% if parameter_ranges is not none %}*Parameter Ranges:* {{parameter_ranges}}{%endif%}
+
+{% if expected_result is not none %}*Expected Result:* {{expected_result}}{%endif%}
+
+*Acceptance Criteria:* {{acceptance_criteria}}
+
+{% if record_environment is not none %}*Runtime Environment:* {{record_environment}}{%endif%}
+
+{% if record_models is not none %}*Simulation Models Used:* {{record_models}}{%endif%}
+
+{% if record_reference_problem is not none %}*Reference Problem:* {{record_reference_problem}}{%endif%}
+
+{% if record_inputs is not none %}*Necessary Inputs for Record:* {{record_inputs}}{%endif%}
+
+{% if record_actions is not none %}*Recort Actions:* {{record_actions}}{%endif%}
+
+
+{{content}}

doc/Makefile

@@ -1,5 +1,4 @@
-# Minimal makefile for Sphinx documentation
-#
+# Minimal makefile for Sphinx documentation for BASH Linux
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
@@ -13,7 +12,7 @@ help:
 
 .PHONY: help Makefile
 
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+# Catch-all target: route all unknown targets to Sphinx using the new "make mode" option.
+# $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)