[DOCUMENTATION] Prototype documentation build glue

.circleci/config.yml

@@ -109,7 +109,7 @@ jobs:
           key: v1-repo-{{ .Environment.CIRCLE_SHA1 }}
       - run:
           shell: /bin/bash
-          name: "setup depends"
+          name: "set up depends"
           command: |
             python3 -m pip install --upgrade --user -r ./requirements.txt || : ;
           when: on_success

.github/workflows/Tests.yml

@@ -87,11 +87,11 @@
       LANG: ${{ matrix.lang-var }}
     steps:
     - uses: actions/checkout@v4
-    - name: Setup Python
+    - name: Set up Python
       uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
-    - name: Setup dependencies
+    - name: Set up dependencies
       run: |
         pip install --upgrade "pip>=21.0" "setuptools>=45.0" "wheel>=0.37" "build>=1.0.1";
         pip install -r ./requirements.txt ;
@@ -145,7 +145,7 @@
       LANG: "en_US.utf-8"
     steps:
     - uses: actions/checkout@v4
-    - name: Setup Python ${{ matrix.python-version }}
+    - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
@@ -154,6 +154,7 @@
         pip install --upgrade "pip>=21.0" "setuptools>=45.0" "wheel>=0.37" "build>=1.0.1";
         pip install -r ./requirements.txt ;
         pip install -r ./tests/requirements.txt || true ;
+        pip install --upgrade -r ./docs/requirements.txt || true ;
     - name: Pre-Clean
       id: clean
       run: make -j1 -f Makefile clean || true ;
@@ -191,9 +192,10 @@
       COV_CORE_DATAFILE: ./coverage.xml
       CODECLIMATE_REPO_TOKEN: ${{ secrets.CODECLIMATE_TOKEN }}
       CC_TEST_REPORTER_ID: ${{ secrets.CC_TEST_REPORTER_ID }}
+      DEEPSOURCE_DSN: ${{ secrets.DEEPSOURCE_DSN }}
     steps:
     - uses: actions/checkout@v4
-    - name: Setup Python ${{ matrix.python-version }}
+    - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
@@ -202,6 +204,7 @@
         pip install --upgrade "pip>=21.0" "setuptools>=45.0" "wheel>=0.37" "build>=1.0.1";
         pip install -r ./requirements.txt ;
         pip install -r ./tests/requirements.txt || true ;
+        pip install --upgrade -r ./docs/requirements.txt || true ;
     - name: Install code-climate tools for ${{ matrix.python-version }}
       if: ${{ runner.os }} == "Linux"
       shell: bash
@@ -273,9 +276,10 @@
       COV_CORE_DATAFILE: ./coverage.xml
       CODECLIMATE_REPO_TOKEN: ${{ secrets.CODECLIMATE_TOKEN }}
       CC_TEST_REPORTER_ID: ${{ secrets.CC_TEST_REPORTER_ID }}
+      DEEPSOURCE_DSN: ${{ secrets.DEEPSOURCE_DSN }}
     steps:
     - uses: actions/checkout@v4
-    - name: Setup Python ${{ matrix.python-version }}
+    - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
@@ -284,6 +288,7 @@
         pip install --upgrade "pip>=21.0" "setuptools>=45.0" "wheel>=0.37" "build>=1.0.1";
         pip install --upgrade -r ./requirements.txt ;
         pip install --upgrade -r ./tests/requirements.txt || true ;
+        pip install --upgrade -r ./docs/requirements.txt || true ;
     - name: Install code-climate tools for ${{ matrix.python-version }}
       if: ${{ runner.os }} == "Linux"
       shell: bash
@@ -349,7 +354,7 @@
 
     steps:
     - uses: actions/checkout@v4
-    - name: Setup Python
+    - name: Set up Python
       uses: actions/setup-python@v5
       with:
         python-version: "3.10"
@@ -358,6 +363,7 @@
         pip install --upgrade "pip>=21.0" "setuptools>=45.0" "wheel>=0.37" "build>=1.0.1";
         pip install --upgrade -r ./requirements.txt ;
         pip install --upgrade -r ./tests/requirements.txt || true ;
+        pip install --upgrade -r ./docs/requirements.txt || true ;
     - name: Pre-Clean
       id: clean
       run: make -j1 -f Makefile clean || true ;
@@ -393,7 +399,7 @@
       CC_TEST_REPORTER_ID: ${{ secrets.CC_TEST_REPORTER_ID }}
     steps:
     - uses: actions/checkout@v4
-    - name: Setup Python ${{ matrix.python-version }}
+    - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
@@ -402,6 +408,7 @@
         pip install --upgrade "pip>=21.0" "setuptools>=45.0" "wheel>=0.37" "build>=1.0.1";
         pip install --upgrade -r ./requirements.txt ;
         pip install --upgrade -r ./tests/requirements.txt || true ;
+        pip install --upgrade -r ./docs/requirements.txt || true ;
     - name: Install code-climate tools for ${{ matrix.python-version }}
       if: ${{ runner.os }} != "Linux"
       run: |
@@ -440,7 +447,7 @@
         fail_ci_if_error: false
     - name: Upload Extra Python ${{ matrix.python-version }} Artifact
       uses: actions/upload-artifact@v4
       with:
         name: Integration-Test-Report-${{ matrix.os }}-${{ matrix.python-version }}
         path: ./test-reports/
         if-no-files-found: ignore
@@ -490,7 +497,7 @@
       CODECLIMATE_REPO_TOKEN: ${{ secrets.CODECLIMATE_TOKEN }}
     steps:
     - uses: actions/checkout@v4
-    - name: Setup Python ${{ matrix.python-version }}
+    - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
@@ -551,7 +558,7 @@
 
     steps:
     - uses: actions/checkout@v4
-    - name: Setup Python
+    - name: Set up Python
       uses: actions/setup-python@v5
       with:
         python-version: "3.12"
@@ -564,6 +571,7 @@
         pip install --upgrade "pip>=21.0" "setuptools>=45.0" "wheel>=0.37" "build>=1.0.1";
         pip install --upgrade -r ./requirements.txt ;
         pip install --upgrade -r ./tests/requirements.txt || true ;
+        pip install --upgrade -r ./docs/requirements.txt || true ;
     - name: Pre-Clean
       id: clean
       run: make -j1 -f Makefile clean || true ;

.gitignore

@@ -109,3 +109,10 @@ ENV/
 *.xcodeproj
 *.xcodeproj/*
 
+# Project Specific
+_build/
+docs/_build/
+docs/www/
+docs/make.bat
+multicast/multicast/**
+tests/tests/**

LICENSE.md

@@ -1,4 +1,4 @@
-License - MIT
+# MIT License
 
 Copyright (c) 2017-2024, Mr. Walls
 
@@ -22,39 +22,49 @@ copies or substantial portions of the Software.
 
 
 
-END MIT License
+***
 
-Included Licenses and additional Acknowledgments included with package:
+## Included Licenses and additional Acknowledgments included with package
 
-Files: `tests/context.py`, `tests/test_basic.py`, and `tests/test_usage.py`
-..........................................
+* Files: `tests/context.py`, `tests/test_basic.py`, and `tests/test_usage.py`
+***
 Copyright (c) 2017-2022, Python Test Repo Template
 ALSO Licensed under MIT
 You may obtain a copy of the License at
-http://www.github.com/reactive-firewall/python-repo/LICENSE.md
-..........................................
+[MIT License](http://www.github.com/reactive-firewall/python-repo/LICENSE.md)
+***
 
-Third-party Acknowledgments:
+## Third-party Acknowledgments
 
-Files: `multicast/send.py` and `multicast/recv.py`
-..........................................
-Some code (namely: run, and parseArgs) was modified/derived from:
-https://stackoverflow.com/a/52791404
-Copyright (c) 2019, "pterodragon" (https://stackoverflow.com/users/5256940/pterodragon)
+* Files: `multicast/send.py` and `multicast/recv.py`
+***
+Some code (namely: run, and parseArgs) was modified/derived from
+[This answer on stackoverflow](https://stackoverflow.com/a/52791404)
+Copyright (c) 2019, ["pterodragon"](https://stackoverflow.com/users/5256940/pterodragon)
 which was under CC-by-sa-4 license.
-see https://creativecommons.org/licenses/by-sa/4.0/ for details
+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 https://creativecommons.org/licenses/by-sa/4.0/ for details
-..........................................
+See [CC-by-sa-4](https://creativecommons.org/licenses/by-sa/4.0/) for details.
+***
 NO ASSOCIATION
 
-Files: `tests/profiling.py`
-..........................................
-Some code (namely: class timewith, @do_cprofile, @do_line_profile) was modified/derived from:
-https://github.com/zapier/profiling-python-like-a-boss/tree/1ab93a1154
+* Files: `tests/profiling.py`
+***
+Some code (namely: class timewith, @do_cprofile, @do_line_profile) was modified/derived from
+[profiling-python-like-a-boss](https://github.com/zapier/profiling-python-like-a-boss/tree/1ab93a1154)
 Copyright (c) 2013, Zapier Inc. All rights reserved.
 which was under BSD-3 Clause license.
-see https://github.com/zapier/profiling-python-like-a-boss/blob/1ab93a1154/LICENSE.md for details
-..........................................
+See [BSD-3 Clause license](https://github.com/zapier/profiling-python-like-a-boss/blob/1ab93a1154/LICENSE.md) for details.
+***
+NO ASSOCIATION
+
+* Files: `docs/config.py`
+***
+Some code (namely: Sphinx setup output config) was modified/derived from
+[Sphinx documentation](https://github.com/sphinx-doc/sphinx/blob/569fde84d49c984282355c768c16426af83132e2/doc/conf.py)
+Copyright (c) 2007-2024 by the Sphinx team. All rights reserved.
+which was under BSD-2 Clause license.
+See [BSD License](https://github.com/sphinx-doc/sphinx/blob/569fde84d49c984282355c768c16426af83132e2/LICENSE.rst) for details.
+***
 NO ASSOCIATION

Makefile

@@ -92,7 +92,7 @@ endif
 
 ifndef PIP_COMMON_FLAGS
 	# Define common pip install flags
-	PIP_COMMON_FLAGS := --use-pep517 --upgrade --upgrade-strategy eager
+	PIP_COMMON_FLAGS := --use-pep517 --exists-action s --upgrade --upgrade-strategy eager
 endif
 
 # Define environment-specific pip install flags
@@ -139,7 +139,7 @@ ifeq "$(RMDIR)" ""
 	RMDIR=$(RM)Rd
 endif
 
-PHONY: cleanup init must_be_root must_have_flake must_have_pytest uninstall
+.PHONY: cleanup init clean-docs must_be_root must_have_flake must_have_pytest uninstall
 
 build: init ./setup.py
 	$(QUIET)$(PYTHON) -W ignore -m build --sdist --wheel --no-isolation ./ || $(QUIET)$(PYTHON) -W ignore -m build ./ ;
@@ -173,6 +173,7 @@ purge: clean uninstall
 
 test: cleanup
 	$(QUIET)$(COVERAGE) run -p --source=multicast -m unittest discover --verbose --buffer -s ./tests -t $(dir $(abspath $(lastword $(MAKEFILE_LIST)))) || $(PYTHON) -m unittest discover --verbose --buffer -s ./tests -t ./ || DO_FAIL="exit 2" ;
+	$(QUITE)$(WAIT) ;
 	$(QUIET)$(DO_FAIL) ;
 	$(QUIET)$(COVERAGE) combine 2>$(ERROR_LOG_PATH) || : ;
 	$(QUIET)$(COVERAGE) report -m --include=* 2>$(ERROR_LOG_PATH) || : ;
@@ -190,14 +191,20 @@ test-reports:
 test-reqs: test-reports init
 	$(QUIET)$(PYTHON) -m pip install $(PIP_COMMON_FLAGS) $(PIP_ENV_FLAGS) -r tests/requirements.txt 2>$(ERROR_LOG_PATH) || true
 
+docs-reqs: ./docs/ ./docs/requirements.txt init
+	$(QUIET)$(PYTHON) -m pip install $(PIP_COMMON_FLAGS) $(PIP_ENV_FLAGS) -r docs/requirements.txt  2>$(ERROR_LOG_PATH) || : ;
+	$(QUIET)$(WAIT) ;
 
 test-pytest: cleanup must_have_pytest test-reports
 	$(QUIET)$(PYTHON) -m pytest --cache-clear --doctest-glob=multicast/*.py,tests/*.py --doctest-modules --cov=. --cov-append --cov-report=xml --junitxml=test-reports/junit.xml -v --rootdir=. || DO_FAIL="exit 2" ;
+	$(QUITE)$(WAIT) ;
 	$(QUIET)$(DO_FAIL) ;
 	$(QUIET)$(ECHO) "$@: Done."
 
 test-style: cleanup must_have_flake
-	$(QUIET)$(PYTHON) -m flake8 --ignore=W191,W391 --max-line-length=100 --verbose --count --config=.flake8.ini --show-source || true
+	$(QUIET)$(PYTHON) -m flake8 --ignore=W191,W391 --max-line-length=100 --verbose --count --config=.flake8.ini --show-source || DO_FAIL="exit 2" ;
+	$(QUITE)$(WAIT) ;
+	$(QUIET)$(DO_FAIL) ;
 	$(QUIET)tests/check_spelling || true
 	$(QUIET)tests/check_cc_lines || true
 	$(QUIET)$(ECHO) "$@: Done."
@@ -254,12 +261,27 @@ cleanup:
 	$(QUIET)$(RMDIR) ./.tox/ 2>$(ERROR_LOG_PATH) || true
 	$(QUIET)$(WAIT) ;
 
+build-docs: ./docs/ ./docs/Makefile docs-reqs
+	$(QUIET)$(MAKE) -s -C ./docs/ -f Makefile html 2>$(ERROR_LOG_PATH) || DO_FAIL="exit 2" ;
+	$(QUIET)$(WAIT) ;
+	$(QUIET)mkdir $(INST_OPTS) ./docs/www 2>$(ERROR_LOG_PATH) >$(ERROR_LOG_PATH) || : ;
+	$(QUIET)$(BSMARK) ./docs/www 2>$(ERROR_LOG_PATH) >$(ERROR_LOG_PATH) || : ;
+	$(QUIET)$(WAIT) ;
+	$(QUIET)cp -fRp ./docs/_build/ ./docs/www/ 2>$(ERROR_LOG_PATH) || DO_FAIL="exit 35" ;
+	$(QUIET)$(WAIT) ;
+	$(QUIET)$(MAKE) -s -C ./docs/ -f Makefile clean 2>$(ERROR_LOG_PATH) || : ;
+	$(QUIET)$(WAIT) ;
+	$(QUIET)$(ECHO) "Documentation should be in docs/www/html/"
+	$(QUIET)$(DO_FAIL) ;
+
 clean-docs: ./docs/ ./docs/Makefile
-	$(QUIET)$(MAKE) -s -C ./docs/ -f Makefile clean 2>$(ERROR_LOG_PATH) || true
+	$(QUIET)$(RM) ./docs/www/* 2>$(ERROR_LOG_PATH) || : ;
+	$(QUIET)$(RMDIR) ./docs/www/ 2>$(ERROR_LOG_PATH) || : ;
+	$(QUIET)$(MAKE) -s -C ./docs/ -f Makefile clean 2>$(ERROR_LOG_PATH) || : ;
 	$(QUIET)$(WAIT) ;
 
 ./docs/:
-	$(QUIET)$(WAIT) ;
+	$(QUIET) : ;
 
 ./docs/Makefile: ./docs/
 	$(QUIET)$(WAIT) ;