Adding Requirements and QA to Docs

.github/workflows/docs.yaml

@@ -33,6 +33,11 @@ jobs:
       - name: Make HTML Docs
         run: |
           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

.gitignore

@@ -7,7 +7,6 @@
 # No build artifacts
 *.dll
 *.lib
-.apidocs/
 /bin
 armi/tests/tutorials/case-suite
 bin/*
@@ -17,6 +16,7 @@ coverage.xml
 coverage_results.*
 dist-*/
 dist/
+doc/.apidocs
 doc/_build
 doc/anl-afci-177
 doc/gallery
@@ -26,6 +26,7 @@ doc/tutorials/case-suite
 doc/user/tutorials
 htmlcov/
 monkeytype.*
+test_results.*
 wheelhouse
 
 # No workspace crumbs

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/conf.py

@@ -62,6 +62,7 @@
 
 APIDOC_REL = ".apidocs"
 SOURCE_DIR = os.path.join("..", "armi")
+STATIC_DIR = ".static"
 _TUTORIAL_FILES = [
     fName for fName in bookkeepingTests.TUTORIAL_FILES if "ipynb" not in fName
 ]
@@ -198,35 +199,14 @@ def run(self):
             return [para]
         except Exception as e:
             docname = self.state.document.settings.env.docname
-            # add the error message directly to the built documentation and also tell the
-            # builder
+            # add the error message directly to the built documentation and also tell the builder
             raise self.error(
                 "Unable to execute embedded doc code at {}:{} ... {}\n{}".format(
                     docname, self.lineno, datetime.datetime.now(), str(e)
                 )
             )
 
 
-class SkipNeedsDirective(Directive):
-    """
-    A no-op directive that filters out any sphinx-need directives from docs.
-
-    Temporary patch until we figure out a different/better way to maintain formal QA docs.
-    """
-
-    has_content = True
-    required_arguments = 1
-    optional_arguments = 0
-    final_argument_whitespace = True
-
-    def run(self):
-        _delete_opt = self.options.get("delete")
-        _collapse = self.options.get("collapse")
-        _jinja_content = self.options.get("jinja_content")
-        _hide = "hide" in self.options
-        return []
-
-
 def autodoc_skip_member_handler(app, what, name, obj, skip, options):
     """Manually exclude certain methods/functions from docs."""
     # exclude special methods from unittest
@@ -249,8 +229,6 @@ def setup(app):
     app.add_domain(PatchedPythonDomain, override=True)
     app.add_directive("exec", ExecDirective)
     app.add_directive("pyreverse", PyReverse)
-    app.add_directive("impl", SkipNeedsDirective)
-    app.add_directive("test", SkipNeedsDirective)
 
     # making tutorial data dir
     dataDir = pathlib.Path("user") / ".." / "anl-afci-177"
@@ -264,9 +242,9 @@ def setup(app):
         safeCopy(path, dataDir)
 
 
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
+# If extensions (or modules to document with autodoc) are in another directory, add these
+# directories to sys.path here. If the directory is relative to the documentation root, use
+# os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath(".."))
 
 # -- General configuration -----------------------------------------------------
@@ -289,6 +267,8 @@ def setup(app):
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
     "sphinx_gallery.gen_gallery",
+    "sphinx_needs",  # needed for requirements tracking
+    "sphinxcontrib.test_reports",
     "sphinx_rtd_theme",  # needed here for loading jquery in sphinx 6
     "sphinx_simplepdf",
     "sphinxcontrib.apidoc",
@@ -302,23 +282,25 @@ def setup(app):
     "members": True,
     "private-members": False,
     "undoc-members": True,
+    "ignore-module-all": True,
 }
 autodoc_member_order = "bysource"
 # this line removes huge numbers of false and misleading, inherited docstrings
 autodoc_inherit_docstrings = False
 autoclass_content = "both"
+autodoc_mock_imports = ["wx"]
 
 apidoc_module_dir = SOURCE_DIR
+apidoc_module_first = True
 apidoc_output_dir = APIDOC_REL
 apidoc_separate_modules = True
-apidoc_module_first = True
 
 # Napoleon settings listed here so we know what's configurable and can track changes (for numpy docstrings)
 napoleon_google_docstring = False
-napoleon_numpy_docstring = True
 napoleon_include_init_with_doc = False
 napoleon_include_private_with_doc = False
 napoleon_include_special_with_doc = False
+napoleon_numpy_docstring = True
 napoleon_use_admonition_for_examples = False
 napoleon_use_admonition_for_notes = True
 napoleon_use_admonition_for_references = False
@@ -349,25 +331,25 @@ def setup(app):
 version = meta.__version__
 release = meta.__version__
 
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-"""
-'library/xml.rst' - ignores the library/xml.rst file (replaces entry in unused_docs)
-'library/xml' - ignores the library/xml directory (replaces entry in exclude_trees)
-'library/xml*' - ignores all files and directories starting with library/xml
-'**/.svn' - ignores all .svn directories (replaces entry in exclude_dirnames)
-"""
+# List of patterns, relative to source directory, that match files and directories to ignore when
+# looking for source files.
 exclude_patterns = [
+    "**.ipynb",
     "**/Python27*",
     "**/ccl*",
-    # prevent sphinx-gallery from causing duplicate source file errors
-    "gallery/**/*.ipynb",
+    "gallery/**/*.ipynb",  # prevent sphinx-gallery from causing duplicate source file errors
     "gallery/**/*.md5",
     "gallery/**/*.zip",
     "gallery/**/*.json",
     "**.ipynb_checkpoints",
+    "**/ccl*",
+    "**/Python27*",
+    "**_reqs.rst",  # needed so included reqs files render
+    ".DS_Store",
     "_build",
-]  # , '**/tests*']
+    "logs",
+    "Thumbs.db",
+]
 
 rst_epilog = r"""
 .. |keff| replace:: k\ :sub:`eff`\
@@ -388,13 +370,12 @@ def setup(app):
 
 # -- Options for HTML output ---------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
+# The theme to use for HTML and HTML Help pages. See the documentation for a list of builtin themes.
 html_theme = "sphinx_rtd_theme"
 
 # (Optional) Logo. Should be small enough to fit the navbar (ideally 24x24).
 # Path should be relative to the ``_static`` files directory.
-html_logo = os.path.join(".static", "armiicon_24x24.ico")
+html_logo = os.path.join(STATIC_DIR, "armiicon_24x24.ico")
 
 # Theme options are theme-specific and customize the look and feel of a theme further.
 html_theme_options = {
@@ -417,12 +398,12 @@ def setup(app):
 
 # The name of an image file (within the static path) to use as favicon of the docs. This file should
 # be a Windows icon file (.ico) being 16x16 or 32x32 pixels large.
-html_favicon = os.path.join(".static", "armiicon_16x16.ico")
+html_favicon = os.path.join(STATIC_DIR, "armiicon_16x16.ico")
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = [".static"]
+html_static_path = [STATIC_DIR]
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -466,7 +447,7 @@ def setup(app):
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
-latex_logo = os.path.join(".static", "armi-logo.png")
+latex_logo = os.path.join(STATIC_DIR, "armi-logo.png")
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
@@ -501,7 +482,7 @@ def setup(app):
         ]
     ),
     "within_subsection_order": FileNameSortKey,
-    "default_thumb_file": os.path.join(".static", "TerraPowerLogo.png"),
+    "default_thumb_file": os.path.join(STATIC_DIR, "TerraPowerLogo.png"),
 }
 
 suppress_warnings = ["autoapi.python_import_resolution"]
@@ -524,7 +505,66 @@ def setup(app):
     image_converter = "magick"
     image_converter_args = ["convert"]
 
+# PDF-only settings
 simplepdf_vars = {
     "links": "#FF3333",
     "primary": "#333333",
 }
+
+# sphinx-needs settings
+needs_statuses = [
+    dict(name=None, description="No status yet; not in any reviews"),
+    dict(
+        name="preliminary",
+        description="Requirement that will have its wording reviewed and/or does not have implementation/testing yet.",
+    ),
+    dict(
+        name="accepted",
+        description="Requirement that either has completed or will undergo TP-ENG-PROC-0013 Appendix D Part 1 review.",
+    ),
+]
+
+needs_extra_options = [
+    "acceptance_criteria",
+    "basis",
+    "subtype",
+]
+
+needs_extra_links = [
+    dict(option="tests", incoming="testing", outgoing="requirements"),
+    dict(option="implements", incoming="implementations", outgoing="requirements"),
+]
+
+# TODO: JOHN Do I need or like these templates and layouts?
+needs_template_folder = os.path.join(STATIC_DIR, "needs_templates")
+needs_layouts = {
+    "test_layout": {
+        "grid": "simple",
+        "layout": {
+            "head": [
+                '<<meta("type_name")>>: **<<meta("title")>>** <<meta_id()>>  <<collapse_button("meta", '
+                'collapsed="icon:arrow-down-circle", visible="icon:arrow-right-circle", initial=False)>> '
+            ],
+            "meta": [
+                "signature: <<meta('signature')>>",
+                "<<meta_links_all()>>",
+            ],
+        },
+    },
+    "req_hide_links": {
+        "grid": "simple",
+        "layout": {
+            "head": [
+                '<<meta("type_name")>>: **<<meta("title")>>** <<meta_id()>>  <<collapse_button("meta", '
+                'collapsed="icon:arrow-down-circle", visible="icon:arrow-right-circle", initial=False)>> '
+            ],
+            "meta": [
+                "<<meta_all(no_links=True, exclude=['layout'])>>",
+            ],
+        },
+    },
+}
+
+
+# Formats need roles (reference to a req in text) as just the req ID
+needs_role_need_template = "{id}"

doc/index.rst

@@ -14,6 +14,7 @@ ARMI
    gallery/index
    tutorials/index
    release/index
+   qa_docs/index
    glossary
    API Docs <.apidocs/modules>
 

doc/qa_docs/index.rst

@@ -0,0 +1,17 @@
+################
+QA Documentation
+################
+
+This is the Quality Assurance (QA) documentation for the Advanced Reactor Modeling Interface (ARMI)
+framework. This document includes the Software Requirements Specification Document (SRSD), the
+Software Design and Implementation Document (SDID), and the Software Test Report (STR).
+
+-------------
+
+.. toctree::
+   :maxdepth: 3
+   :numbered:
+
+   srsd
+   sdid
+   str