fix: doc: add short doorstop intro, cleanup rst and markdown formatting nits

Signed-off-by: Stephen L Arnold <[email protected]>

Author: sarnold

README.rst

@@ -14,6 +14,9 @@ To create a new repository using this template, click the button labeled
 
 |tag| |license| |reuse| |python|
 
+Template repo cleanup
+~~~~~~~~~~~~~~~~~~~~~
+
 After creating your repository, replace the example project name "simple"
 with your own:
 
@@ -23,8 +26,8 @@ with your own:
 
   + ``find . -name .doorstop.yml`` and review/edit all files
 
-+ then replace all the doorstop content with your own project details
-+ create more doorstop items as needed, link specific design and test
+* then replace all the doorstop content with your own project details
+* create more doorstop items as needed, link specific design and test
   elements back to related **Shall** statements
 * change the author details in ``pyproject.toml`` *and* ``docs/source/conf.py``
 * change the package directory name under the ``src`` folder
@@ -103,11 +106,57 @@ extra features:
 
 
 Dev tools
-=========
+~~~~~~~~~
 
 Local tool dependencies to aid in development; install them for
 maximum enjoyment.
 
+Doorstop
+--------
+
+Initial configurations and first-item doc stubs have been created in the
+following directories::
+
+  $ tree reqs/ docs/swd/ tests/docs/
+  reqs/
+  ├── .doorstop.yml
+  └── REQ001.yml
+  docs/swd/
+  ├── assets
+  │   ├── .gitkeep
+  │   └── simple_dependency_graph.svg
+  ├── .doorstop.yml
+  └── SDD001.md
+  tests/docs/
+  ├── .doorstop.yml
+  └── TST001.yml
+
+The doorstop tool has been added to project [dev] "extras" as well as the
+tox dev and docs environments. Use the "dev" environment for working with
+doorstop_ documents, eg::
+
+  tox -e dev
+  source .venv/bin/activate
+  (.venv) doorstop
+  building tree...
+  loading documents...
+  validating items...
+  WARNING: SDD: SDD001: unreviewed changes
+
+  REQ
+  │
+  ├── TST
+  │
+  └── SDD
+
+
+Please see the doorstop Quick Start for an overview of the relevant doorstop
+commands.
+
+.. _doorstop Quick Start: https://doorstop.readthedocs.io/en/latest/getting-started/quickstart.html
+.. _doorstop: https://doorstop.readthedocs.io/en/latest/index.html
+
+
 Tox
 ---
 
@@ -194,7 +243,7 @@ It's usually a good idea to update the hooks to the latest version::
 
 
 SBOM and license info
-=====================
+~~~~~~~~~~~~~~~~~~~~~
 
 This project is now compliant with the REUSE Specification Version 3.3, so the
 corresponding license information for all files can be found in the ``REUSE.toml``

docs/swd/SDD001.md

@@ -13,7 +13,7 @@ level: 1.0
 links: []
 normative: false
 ref: ''
-reviewed: 4BiP2t0Xpr2CU1F7UpuJDZ8ZYba_FwhAHm7uXIphy2I=
+reviewed: niwzsx_UYtwjd_p6uGIruhDROomRv8QMNBKnC_2d0Qg=
 ---
 
 # Design Elements
@@ -40,7 +40,7 @@ Simple Software Units (captured from mermaid to SVG or PNG).
   <summary>simple_dependency_graph source</summary>
   simple dependency graph showing primary software units.
 
-```mermaid
+```
   graph TB
     subgraph id1[simple Dependencies]
       subgraph id2[Python Packages]
@@ -57,4 +57,4 @@ Simple Software Units (captured from mermaid to SVG or PNG).
 
 ## Design decisions
 
-More text here.
+More text here.