chg: dev: update doc and project files, add minimal doorstop stub docs

* note readme needs an intro to doorstop and some normative items

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

Author: sarnold

.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

@@ -19,6 +19,9 @@ 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
+
 * 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``
@@ -267,10 +270,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/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/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/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,54 @@
+---
+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: 4BiP2t0Xpr2CU1F7UpuJDZ8ZYba_FwhAHm7uXIphy2I=
+---
+
+# 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:
+
+![simple software units](assets/simple_dependency_graph.svg)
+
+<details>
+  <summary>simple_dependency_graph source</summary>
+  simple dependency graph showing primary software units.
+
+```mermaid
+  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.

docs/swd/assets/.gitkeep

@@ -18,14 +18,15 @@ authors = [
 ]
 
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Environment :: Console",
+    "Framework :: tox",
     "Intended Audience :: Developers",
     "Operating System :: POSIX :: Linux",
     "Operating System :: Unix",
     "Programming Language :: Python :: 3",
     "Topic :: Documentation",
-    "Topic :: Multimedia :: Graphics",
+    "Topic :: Software Development",
     "Topic :: Software Development :: Libraries",
     "Topic :: Software Development :: Documentation",
     "Topic :: Software Development :: Testing",
@@ -40,6 +41,7 @@ requires-python = ">=3.9"
 
 [project.optional-dependencies]
 dev = [
+    "doorstop",
     "flake8",
     "isort",
     "mypy>=0.990",
@@ -52,12 +54,12 @@ cov = [
 ]
 doc = [
     "sphinx",
-    "sphinxcontrib.apidoc",
     "sphinx_git",
-    "myst-parser",
-    "sphinxcontrib.mermaid",
+    "sphinxcontrib.apidoc",
     "sphinx_rtd_theme<3.0",  # for the version display
     "sphinx-nefertiti",
+    "myst-parser",
+    #"sphinxcontrib.mermaid",
 ]
 test = [
     "pytest",
@@ -85,7 +87,7 @@ markers = "subscript"
 
 [tool.coverage.run]
 branch = true
-source_pkgs = ["src"]
+source_pkgs = ["src/simple"]
 omit = [
     "setup.py",
     "scripts",

pyproject.toml

@@ -0,0 +1,22 @@
+settings:
+  digits: 3
+  itemformat: yaml
+  prefix: REQ
+  sep: ''
+attributes:
+  reviewed:
+    - short-name
+  defaults:
+    short-name: ''
+    doc:
+      name: simple
+      title: Requirements for _simple_
+      ref: ''
+      by: tdeveloper
+      major: '1'
+      minor: A
+      copyright: tdeveloper
+  publish:
+    - commentary
+    - rationale
+    - normative

reqs/.doorstop.yml

@@ -0,0 +1,42 @@
+active: true
+derived: false
+doc:
+  by: sarnold
+  copyright: tdeveloper
+  major: '1'
+  minor: A
+  name: simple
+  ref: ''
+  title: Requirements for _simple_
+header: ''
+level: 1.0
+links: []
+normative: false
+ref: ''
+reviewed: 3tp2D2vihFUgViix5tF_Ez6tAyWKm1Vd75Te-3kQ0xs=
+short-name: reqs_overview
+text: |
+  Requirements overview
+
+  The simple package is intended to provide a simple but modern example of
+  creating a project/package using setuptools/setuptools-scm with the latest
+  metadata and default build backend for PEP517 compliance.
+
+  The main dependencies are shown below.
+
+  - [importlib-metadata](https://pypi.org/project/importlib-metadata/)
+    - used for runtime version retrieval (for older Python)
+  - [munch](https://github.com/Infinidat/munch)
+    - an example convenience library for adding attribute access to dictionaries
+
+  The simple package should demonstrate the following items.
+
+  - project metadata and tool configuration in pyproject.toml
+  - project docs with auto-generated requirements, SW design, and API/interfaces
+  - getting-started setup doc and github/tox workflow automation
+  - working pre-commit configuration and REUSE license compliance
+
+  > [!IMPORTANT]
+  > The above item `short_name` is a custom doorstop attribute and
+  > must be added to the doorstop config file, as well as populated
+  > with the desired "alias" for the given item.