[MERGE]

Author: reactive-firewall

.github/workflows/Tests.yml

@@ -1,5 +1,24 @@
 ---
 name: CI
+# Continuous Integration workflow for building, testing, and validating the project
+#
+# Jobs included:
+# - BUILD: Ensures the project compiles correctly
+# - BOOTSTRAP: Tests installation across Python versions and locales
+# - MATS: Runs Machine Acceptance Tests
+# - COVERAGE: Generates coverage reports on multiple OS and Python versions
+# - STYLE: Checks code style and linting compliance
+# - INTEGRATION: Performs integration tests on different platforms
+# - EXTRAS-FOR-SETUP: Tests legacy setup scripts
+# - EXTRAS-FOR-PIP: Validates package dependencies and pip installations
+# - DOCS: Builds and lints documentation
+# - TOX: Executes tests across Python environments using Tox
+#
+# Required Secrets:
+# - CODECOV_TOKEN: For uploading coverage reports to Codecov
+# - CODECLIMATE_TOKEN: For integration with Code Climate
+# - CC_TEST_REPORTER_ID: For Code Climate test reporting
+
 on:  # yamllint disable-line rule:truthy
   push:
     branches:
@@ -600,7 +619,7 @@ jobs:
       PYTHON_VERSION: ${{ matrix.python-version }}
       LANG: "en_US.utf-8"
       LC_CTYPE: "en_US.utf-8"
-      DOCS_BUILD_REF: ${{ github.sha }}
+      DOCS_BUILD_REF: ${{ github.sha }}  # Reference the specific commit in documentation builds
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}

.markdownlint.yaml

@@ -6,15 +6,16 @@ MD001: true   # Enforce proper heading increments
 MD026:  # Disallow trailing punctuation in headings
   punctuation: ",;:!"  # - ('1.', '2.', etc. are ok though)
 
-# Disable or customize rules
+# Disable rules
+MD034: false  # Allow bare URLs
+
+# Customizations
 MD013:  # Disable line length rule for flexibility
   line_length: 100
   code_blocks: false
   tables: false
-MD033: true  # Allow inline HTML if needed
-MD034: false  # Allow bare URLs
-
-# Customizations
+MD033:  # Allow inline HTML if needed
+  allowed_elements: ["details", "summary"]
 MD007:
   indent: 2  # Set unordered list indentation to 2 spaces
 MD029:

.readthedocs.yaml

@@ -5,6 +5,9 @@
 # Required
 version: 2
 
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
 python:
   install:
     - requirements: requirements.txt
@@ -18,17 +21,26 @@ build:
     python: "3.12"
   jobs:
     post_checkout:
+      # Fetch the complete git history; ignore errors if already fully fetched
       - git fetch --unshallow || true
+      # Set fetch configuration to include all branches; ignore errors if already set
       - git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*' || true
+      # Fetch all branches and tags; ignore network errors
       - git fetch --all --tags || true
+      # Clean build artifacts; ignore if already clean
       - make clean || true
+      # Purge caches and temporary files; continue even if purge fails
       - make purge || true
     post_install:
+      # Clean build artifacts; ignore if already clean
       - make clean || true
     pre_build:
+      # Build the project module that is to be documented ; continue even if build fails
       - make build || true
-      - make -j1 build-docs || true
+      # Build docs and verify output exists
+      - make -j1 build-docs && test -d docs/www/_build/html
     post_build:
+      # Move built documentation into place ; ignore if fails
       - cp -vfRp docs/www/_build/html/ "$READTHEDOCS_OUTPUT" || true
 
 # Build documentation in the "docs/" directory with Sphinx
@@ -38,13 +50,14 @@ sphinx:
   fail_on_warning: false
 
 # Optionally build your docs in additional formats such as PDF and ePub
+# To enable, uncomment the following lines and ensure dependencies are met
 # formats:
-#    - pdf
-#    - epub
-
-# Optional but recommended, declare the Python requirements required
-# to build your documentation
-# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
-# python:
-#    install:
-#    - requirements: docs/requirements.txt
+#   - pdf
+#   - epub
+#
+# Note:
+# - Enabling PDF output requires LaTeX installed in the build environment
+#   - PDF output requires texlive-latex-recommended and texlive-fonts-recommended packages
+#   - PDF builds may significantly increase build time and output size
+# - Ensure all documentation content is compatible with these formats
+# - Assess user demand for offline documentation before enabling

LICENSE.md

@@ -44,6 +44,17 @@ You may obtain a copy of the License at
 
 ## Third-party Acknowledgments :bow:
 
+### Files: `Logo.svg`
+
+***
+The logo SVG file references, and when possible renders with, the font
+[CommicNeue](https://github.com/crozynski/comicneue/).
+Copyright 2014 The Comic Neue Project Authors (https://github.com/crozynski/comicneue)
+which was under an OFL-type license.
+See [OFL](https://raw.githubusercontent.com/crozynski/comicneue/d248cfb9/OFL.txt) for details.
+_NO ASSOCIATION._
+***
+
 ### Files: `multicast/send.py` and `multicast/recv.py`
 
 ***
@@ -52,9 +63,8 @@ Some code (namely: run, and parseArgs) was modified/derived from
 Copyright (c) 2019, ["pterodragon"](https://stackoverflow.com/users/5256940/pterodragon)
 which was under CC-by-sa-4 license.
 See [CC-by-sa-4](https://creativecommons.org/licenses/by-sa/4.0/) for details.
-The code in `parseArgs`, `run`, and `main` are thus also under
-CC-by-sa-4
-See [CC-by-sa-4](https://creativecommons.org/licenses/by-sa/4.0/) for details.
+The code in `parseArgs`, `run`, and `main` are thus **also** under
+[CC-by-sa-4](https://creativecommons.org/licenses/by-sa/4.0/) when regarded as source-code.
 _NO ASSOCIATION._
 ***
 

Logo.svg

@@ -329,7 +329,9 @@ clean-docs: ./docs/ ./docs/Makefile
 	$(QUIET)$(WAIT) ;
 
 ./docs/:
-	$(QUIET) : ;
+	$(QUIET)test -d "$@" || DO_FAIL="exit 77" ;  # set fail if can't verify directory
+	$(QUIET)test -e "$@" || DO_FAIL="exit 69" ;  # overwrite exitcode if does not exsist.
+	$(QUIET)$(DO_FAIL) ;
 
 ./docs/Makefile: ./docs/
 	$(QUIET)$(WAIT) ;

Makefile

@@ -1,5 +1,7 @@
 # Multicast Python Repo
 
+![Mcast Logo](Logo.svg)
+
 ## Introduction
 
 The `multicast` package is a Python library that simplifies sending and receiving multicast network