Filling out STR

Author: john-science

.github/workflows/docs.yaml

@@ -33,7 +33,11 @@ jobs:
       - name: Make HTML Docs
         run: |
           pip install -e .[memprof,mpi,test,docs]
-          pytest --junit-xml=test_results.xml -n 4 armi
+          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

doc/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -v
+SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build

doc/conf.py

@@ -40,8 +40,6 @@
 from docutils.parsers.rst import Directive, directives
 from sphinx.domains.python import PythonDomain
 
-# from sphinx_needs.api import add_dynamic_function  # TODO: JOHN
-
 # handle python import locations for this execution
 PYTHONPATH = os.path.abspath("..")
 sys.path.insert(0, PYTHONPATH)
@@ -67,66 +65,6 @@
 _TUTORIAL_FILES = [
     fName for fName in bookkeepingTests.TUTORIAL_FILES if "ipynb" not in fName
 ]
-TEST_RESULTS = []
-
-
-def getTestResult(app, need, needs):
-    """Dynamic function used by sphinx-needs to gather the result of a test tag."""
-    if not need["signature"]:
-        return "none"
-
-    # Get all the tests that match the method signature
-    results = [
-        test_case["result"]
-        for test_case in TEST_RESULTS
-        if need["signature"] == test_case["method"]
-    ]
-    # Logic is as follows if there are multiple matches:
-    #   - If one is a "failure", then return "failure"
-    #   - If all are "skipped", then return "skipped"
-    #   - Otherwise, return "passed"
-    if results:
-        if "failure" in results:
-            return "failure"
-        elif "passed" in results:
-            return "passed"
-        else:
-            return "skipped"
-
-    # Things get a little more complicated when the test tag has a class-level signature.
-    # Basically we have to determine if all the methods in the class passed or if any of skipped/failed.
-    # First, gather all the results related to the class signature from the tag and categorize by method
-    results = {}
-    for test_case in TEST_RESULTS:
-        if need["signature"] == test_case["class"]:
-            if test_case["method"] in results:
-                results[test_case["method"]].append(test_case["result"])
-            else:
-                results[test_case["method"]] = [test_case["result"]]
-
-    # If we haven't found the test by now, we never will
-    if not results:
-        return "none"
-
-    # Apply logic from before for each method in the class
-    for m, r in results.items():
-        if "failure" in r:
-            results[m] = "failure"
-        elif "passed" in r:
-            results[m] = "passed"
-        else:
-            results[m] = "skipped"
-
-    # Now for the class logic
-    #  - If any of the methods failed, return "failure"
-    #  - If any of the methods skipped, return "skipped"
-    #  - If all of the methods passed, return "passed"
-    if "failure" in results.values():
-        return "failure"
-    elif "skipped" in results.values():
-        return "skipped"
-    else:
-        return "passed"
 
 
 class PatchedPythonDomain(PythonDomain):
@@ -287,31 +225,12 @@ def autodoc_skip_member_handler(app, what, name, obj, skip, options):
     return name.startswith("_") or name in excludes
 
 
-def getTestAcceptanceCriteria(app, need, needs):
-    # Return title if there is not just one requirement or the linked requirement doesn't exist
-    if len(need.get("tests", [])) != 1 or need["tests"][0] not in needs:
-        ac = need["title"].strip()
-
-    req = needs[need["tests"][0]]
-    # Return title if there is not just one test in the requirement
-    if len(req.get("tests_back", [])) != 1:
-        ac = need["title"].strip()
-    else:
-        ac = req["acceptance_criteria"].strip()
-
-    # For some reason sphinx is adding another period at the end of this, so we'll just remove it
-    return ac[:-1] if ac[-1] == "." else ac
-
-
 def setup(app):
     """Method to make `make html` generate api documentation."""
     app.connect("autodoc-skip-member", autodoc_skip_member_handler)
     app.add_domain(PatchedPythonDomain, override=True)
     app.add_directive("exec", ExecDirective)
     app.add_directive("pyreverse", PyReverse)
-    # add_dynamic_function(app, getTestAcceptanceCriteria, "get_test_acceptance_criteria")  # TODO: JOHN
-    # add_dynamic_function(app, getTestResult, "get_test_result")
-    # add_dynamic_function(app, getTestAcceptanceCriteria, "get_test_acceptance_criteria")
 
     # making tutorial data dir
     dataDir = pathlib.Path("user") / ".." / "anl-afci-177"
@@ -645,20 +564,6 @@ def setup(app):
     },
 }
 
-# TODO: JOHN
-"""
-needs_global_options = {
-    # Defaults for test tags
-    "acceptance_criteria": (
-        ":ndf:`get_test_acceptance_criteria()`.",
-        "type=='test'",
-    ),
-    "template": ("test", "type=='test'"),
-    "layout": ("test_layout", "type=='test'"),
-    "result": ("[[get_test_result()]]", "type=='test'"),
-}
-"""
-
 
 # Formats need roles (reference to a req in text) as just the req ID
 needs_role_need_template = "{id}"

doc/qa_docs/index.rst

@@ -2,9 +2,9 @@
 QA Documentation
 ################
 
-This is the 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).
+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).
 
 -------------
 
@@ -14,4 +14,4 @@ Implementation Document (SDID), and the Software Test Report (STR).
 
    srsd
    sdid
-   str
+   str