baseline doc updates

.gitchangelog.rc

@@ -61,6 +61,7 @@
 ignore_regexps = [
     r'^([cC]i)\s*:',
     r'dependabot',
+    r'automated change',
     r'@minor', r'!minor',
     r'@cosmetic', r'!cosmetic',
     r'@refactor', r'!refactor',

README.rst

@@ -14,11 +14,21 @@ 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:
 
 * change the project name at the top of ``pyproject.toml``
 * change the project name in ``docs/source/conf.py`` *and* ``docs/source/index.rst``
+* change the author and copyright names in all the doorstop doc and config files, ie
+
+  + ``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
+  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
 * change the github URL paths in ``pyproject.toml``
@@ -96,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
 ---
 
@@ -187,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``
@@ -267,10 +323,10 @@ specifications.
     :target: https://www.python.org/downloads/
     :alt: Python
 
-.. |reuse| image:: https://api.reuse.software/badge/git.fsfe.org/reuse/api
-    :target: https://api.reuse.software/info/git.fsfe.org/reuse/api
+.. |reuse| image:: https://img.shields.io/badge/REUSE-compliant-blue.svg
+    :target: https://reuse.software/spec-3.3/
     :alt: REUSE status
 
 .. |pre| image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white
-   :target: https://github.com/pre-commit/pre-commit
-   :alt: pre-commit
+    :target: https://github.com/pre-commit/pre-commit
+    :alt: pre-commit

docs/process_md_urls.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python
+
+"""
+Get the path to markdown files and process image URLs based on files in
+args. One or more (SVG or PNG) files are required.
+"""
+import os
+import sys
+from pathlib import Path
+from string import Template
+from typing import List, Tuple
+
+DEBUG = int(os.getenv('DEBUG', default='0'))
+EXTENSIONS = ['.svg', '.png']
+
+FIG_TPL = """```{figure} ${figure_path}
+:width: 90 %
+:align: center
+:alt: ${caption_lc}
+
+${caption_title} (captured from mermaid to SVG or PNG).
+```
+"""
+
+CTX = {
+    'caption_lc': '',
+    'caption_title': '',
+    'figure_path': '',
+}
+
+
+def render_caption(caption: str, path: str):
+    """
+    Render a string template.
+    """
+    CTX.update(
+        {
+            'caption_lc': caption.lower(),
+            'caption_title': caption.title(),
+            'figure_path': path,
+        }
+    )
+    return Template(FIG_TPL).substitute(CTX)
+
+
+def find_mdfiles(
+    start: str = '.', fglob: str = '*.md', excludes: Tuple = ('.github', '.tox', '.venv')
+) -> List:
+    """
+    Find markdown files subject to specified exclude paths.
+
+    :param start: directory to start file search
+    :param fglob: file extension glob
+    :param excludes: tuple of excludes
+    """
+    target_files: List = []
+    files = Path(start).rglob(fglob)
+    for file in list(files):
+        if str(file).startswith(excludes):
+            continue
+        target_files.append(file)
+    if DEBUG:
+        print(f'Found file list: {target_files}')
+    return target_files
+
+
+def process_files(new_files: List, target_files: List):
+    """
+    process files if we found enough of each.
+    """
+    for img_file in new_files:
+        for md_file in target_files:
+            doc_str = Path(md_file).read_text(encoding='utf-8')
+            if Path(img_file).name not in doc_str:
+                continue
+            with Path(md_file).open(encoding='utf-8') as file:
+                lines = file.readlines()
+            with Path(md_file).open(mode='w', encoding='utf-8') as file:
+                for line in lines:
+                    if line.startswith(('![', '[')) and Path(img_file).name in line:
+                        if DEBUG:
+                            print(line)
+                        cap_str = line.split('[', 1)[1].split(']')[0]
+                        path_str = line.split('(', 1)[1].split(')')[0]
+                        text = render_caption(cap_str, path_str)
+                        file.write(text + '\n')
+                    else:
+                        file.write(line)
+
+
+def main(argv: list[str] | None = None) -> None:
+    """
+    Runs the program.
+
+    Args:
+        argv: A list of arguments, not including the prog name.
+    """
+    if not argv:
+        if DEBUG:
+            print("No image files, nothing to do ...")
+        sys.exit(0)
+
+    if DEBUG:
+        print(argv)
+    new_files = [f for f in argv if Path(f).suffix in EXTENSIONS and Path(f).exists()]
+    if len(new_files) < 1:
+        if DEBUG:
+            print(f"No valid input files (only {EXTENSIONS} are allowed)")
+        sys.exit(1)
+    if DEBUG:
+        print(new_files)
+
+    target_files = find_mdfiles()
+    if not target_files:
+        if DEBUG:
+            print("No markdown files, nothing to do ...")
+        sys.exit(0)
+
+    if DEBUG:
+        print(target_files)
+
+    process_files(new_files, target_files)
+
+
+# print(','.join(target_files))
+
+if __name__ == "__main__":
+    main(sys.argv[1:])

docs/source/conf.py

@@ -3,10 +3,7 @@
 
 from datetime import datetime
 
-if sys.version_info < (3, 8):
-    from importlib_metadata import version
-else:
-    from importlib.metadata import version
+from importlib.metadata import version
 
 sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..')))
 
@@ -49,14 +46,20 @@
     'sphinx.ext.coverage',
     'sphinx.ext.viewcode',
     'myst_parser',
+    #'sphinxcontrib.mermaid',
 ]
 
+#myst_fence_as_directive = ["mermaid"]
+myst_suppress_warnings = ["myst.header"]
+myst_enable_extensions = ["attrs_inline", "deflist", "fieldlist", "substitution",]
+
 # sphinxcontrib.apidoc
 apidoc_module_dir = f'../../src/{project}'
 apidoc_output_dir = 'api'
 apidoc_excluded_paths = ['scripts', 'tests']
 apidoc_module_first = True
 apidoc_separate_modules = True
+
 autodoc_typehints = 'description'
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/ds/.gitignore

@@ -0,0 +1,2 @@
+*.svg
+/*.md

docs/source/index.rst

@@ -13,6 +13,9 @@ Simple API and SW Docs
     :maxdepth: 1
     :caption: Contents:
 
+    ds/reqs_tree
+    ds/sw_design
+    ds/unit_tests
     README
     api/modules
     dev/generate-changelog

docs/sphinx_prep.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+#
+# This removes ToC section from doorstop-generated markdown.
+# We need to cleanup sphinx doc list and quiet MyST warnings.
+
+set -euo pipefail
+
+failures=0
+trap 'failures=$((failures+1))' ERR
+
+FILE_ARG=${1}
+
+echo "Processing markdown file: ${FILE_ARG}"
+sed -i '/^# 1.0/,$!d' $FILE_ARG
+
+if ((failures == 0)); then
+    echo "Success"
+else
+    echo "Something went wrong"
+    exit 1
+fi

docs/swd/.doorstop.yml

@@ -0,0 +1,21 @@
+settings:
+  digits: 3
+  itemformat: markdown
+  parent: REQ
+  prefix: SDD
+  sep: ''
+extensions:
+  item_sha_required: true  # sha256
+attributes:
+  defaults:
+    doc:
+      name: SW Design
+      title: SW Design Description
+      ref: ''
+      by: tdeveloper
+      major: '1'
+      minor: A
+      copyright: tdeveloper
+  publish:
+    - commentary
+    - rationale

docs/swd/SDD001.md

@@ -0,0 +1,60 @@
+---
+active: true
+derived: false
+doc:
+  by: tdeveloper
+  copyright: tdeveloper
+  major: '1'
+  minor: A
+  name: SW Design
+  ref: ''
+  title: SW Design Description
+level: 1.0
+links: []
+normative: false
+ref: ''
+reviewed: niwzsx_UYtwjd_p6uGIruhDROomRv8QMNBKnC_2d0Qg=
+---
+
+# Design Elements
+
+The simple package provides a convenient example and baseline project
+structure for demonstrating current packaging standards with dynamic
+versioning using the core setuptools package and default PEP517 build
+backend.
+
+The primary install dependencies are importlib-metadata, doorstop, and
+munch, where doorstop is primarily an offline dependency for managing
+requirements data. Complete package dependencies are shown in the
+figure below:
+
+```{figure} assets/simple_dependency_graph.svg
+:width: 90 %
+:align: center
+:alt: simple software units
+
+Simple Software Units (captured from mermaid to SVG or PNG).
+```
+
+<details>
+  <summary>simple_dependency_graph source</summary>
+  simple dependency graph showing primary software units.
+
+```
+  graph TB
+    subgraph id1[simple Dependencies]
+      subgraph id2[Python Packages]
+        A(simple)
+        B(importlib-metadata)
+        C(munch)
+        D{doorstop}
+      end
+    end
+    A ==> B & C & D
+    D -.-> A
+```
+</details>
+
+## Design decisions
+
+More text here.