Adding Requirements and QA to Docs

[john-science]

What is the change?

Here I add a "QA Documentation" section to the ARMI docs. This section will have:

• Open-Sourced ARMI Requirements
• Software Requirements Specification Document (SRSD)
• Software Design and Implementation Document (SDID)
• Software Test Report (STR)

Why is the change being made?

close #2064

This is part of on-going work to improve the documentation of ARMI's high-level design requirements, and to open-source that information.

SCR Information

Change Type: docs

One-Sentence Description: Here I add a "QA Documentation" section to the ARMI docs.

One-line Impact on Requirements: NA

---

Checklist

• This PR has only one purpose or idea.
• Tests have been added/updated to verify any new/changed code.

• The code style follows good practices.
• The commit message(s) follow good practices.

• The release notes have been updated if necessary.
• The documentation is still up-to-date in the doc folder.
• The dependencies are still up-to-date in pyproject.toml.

[john-science]

Okay, this appears to work fine. Here are some examples. First, the TOC at the top now includes this:

The sphinx-needs tooling is working:

The SDID looks fine:

The STR matrix is working:

[john-science]

Okay, this is working great.

But I am now getting a TON of Sphinx warnings:

WARNING: Ignored `filter:progid:DXImageTransform.Microsoft.gradient(GradientType=0,StartColorStr="#f9f9f9", EndColorStr="#e0e0e0")` at 16:4443, unknown property.
WARNING: Ignored `text-shadow:0 1px 0 #c4def1` at 16:4687, unknown property.
WARNING: Ignored `background-image:-webkit-linear-gradient(top, #bddef4 0%, #79ace9 100%)` at 16:4753, invalid value.
WARNING: Ignored `background-image:-o-linear-gradient(top, #f0f0f0 0%, #dadada 100%)` at 16:6528, invalid value.
WARNING: Ignored `filter:progid:DXImageTransform.Microsoft.gradient(GradientType=0,StartColorStr="#f0f0f0", 
WARNING: Ignored `box-shadow:0 0 3px #444` at 28:2080, unknown property.
WARNING: Anchor defined twice: 'setting-up-the-blueprints'
WARNING: Anchor defined twice: 'nuclide-flags'
WARNING: Anchor defined twice: 'defining-fuel-management'
WARNING: Anchor defined twice: 'id13'
WARNING: Anchor defined twice: 'new-features'
WARNING: Anchor defined twice: 'api-changes'
WARNING: Anchor defined twice: 'bug-fixes'
WARNING: Anchor defined twice: 'quality-work'
WARNING: Anchor defined twice: 'bug-fixes'
WARNING: Anchor defined twice: 'quality-work'
WARNING: Anchor defined twice: 'subpackages'
WARNING: Anchor defined twice: 'submodules'
WARNING: Anchor defined twice: 'T_ARMI_MAT_PROPERTIES1'
WARNING: Anchor defined twice: 'T_ARMI_MAT_FLUID0'
WARNING: Anchor defined twice: 'submodules'
WARNING: Anchor defined twice: 'id1'
WARNING: Anchor defined twice: 'id2'
WARNING: Anchor defined twice: 'I_ARMI_MAT_FLUID'

The docs look fine though.

[opotowsky]

Okay, this is working great.

But I am now getting a TON of Sphinx warnings:

WARNING: Ignored `filter:progid:DXImageTransform.Microsoft.gradient(GradientType=0,StartColorStr="#f9f9f9", EndColorStr="#e0e0e0")` at 16:4443, unknown property.
WARNING: Ignored `text-shadow:0 1px 0 #c4def1` at 16:4687, unknown property.
WARNING: Ignored `background-image:-webkit-linear-gradient(top, #bddef4 0%, #79ace9 100%)` at 16:4753, invalid value.
WARNING: Ignored `background-image:-o-linear-gradient(top, #f0f0f0 0%, #dadada 100%)` at 16:6528, invalid value.
WARNING: Ignored `filter:progid:DXImageTransform.Microsoft.gradient(GradientType=0,StartColorStr="#f0f0f0", 
WARNING: Ignored `box-shadow:0 0 3px #444` at 28:2080, unknown property.
WARNING: Anchor defined twice: 'setting-up-the-blueprints'
WARNING: Anchor defined twice: 'nuclide-flags'
WARNING: Anchor defined twice: 'defining-fuel-management'
WARNING: Anchor defined twice: 'id13'
WARNING: Anchor defined twice: 'new-features'
WARNING: Anchor defined twice: 'api-changes'
WARNING: Anchor defined twice: 'bug-fixes'
WARNING: Anchor defined twice: 'quality-work'
WARNING: Anchor defined twice: 'bug-fixes'
WARNING: Anchor defined twice: 'quality-work'
WARNING: Anchor defined twice: 'subpackages'
WARNING: Anchor defined twice: 'submodules'
WARNING: Anchor defined twice: 'T_ARMI_MAT_PROPERTIES1'
WARNING: Anchor defined twice: 'T_ARMI_MAT_FLUID0'
WARNING: Anchor defined twice: 'submodules'
WARNING: Anchor defined twice: 'id1'
WARNING: Anchor defined twice: 'id2'
WARNING: Anchor defined twice: 'I_ARMI_MAT_FLUID'

The docs look fine though.

This is probably because you have a file getting processed by sphinx 2x somewhere via an include. If you add that file to exclude_patterns in your conf.py you should be able to get rid of these. I think. I've spent 0 time confirming this.

[opotowsky]

I'll review this at the high level (not commenting on content since that is being reviewed by @ntouran)

There are minor formatting issues with the PDF (some tables and text includes run off the page, and some math isn't rendering in the PDF that renders fine in HTML. I sent screencaps to you offline.

In the QA section (HTML), it appears I can click from an impl or test back to a requirement, but I can't click the impl/test link from the requirement (I get a "page does not exist" error).

Looks good though! Let me know if some of these things I commented on are out of scope.

[opotowsky]

ok after all the troubleshooting, I re-approve!