Documentation Technical debt

[reactive-firewall]

• documentation technical-debt
  • Docstrings are present and all have a one-sentance (that fits on one line) description at start of their docstrings for all:
    • modules
      • functions
      • classes
        • class methods,
          - [ ] class attributes
    • and it is all tested
  • documentation of functions, class methods, have a description of any relevant arguments somewhere in their docstrings
  • documentation of modules, functions, classes, non-abstract-class methods, class attributes all have a minimal acceptance test in the form of a doctest somewhere in their docstrings (of-course they may also have extra tests)
  • sphinx can build docs without crashing
    • Next steps: implement a linter step called "Lint documentation" in CI job "DOCS"
    • Next steps: verify links work for CI artifacts use-case
      • moving to 'docs/www' from docs/_build breaks relative links right now
      • some links still point at .md copy when they should be re-written during sphinx operations to .html or .pdf etc (based on output)