[DOCUMENTATION] Implemented #240

Additions with file docs/utils.py:
 - moved validation and formating functions into utilities module.

Changes in file docs/conf.py:
 - moved `_validate_git_ref` function
 - added `sphinx_design` extension
 - improved configuration settings for markdown docs

Changes in file docs/requirements.txt:
 - added `sphinx_design` for documentation building

Changes in file pyproject.toml:
 - aligned tool settings with CEP-7

Author: reactive-firewall

docs/conf.py

@@ -40,52 +40,13 @@
 import sys
 import os
 from urllib.parse import quote
-import re
-
-
-def _validate_git_ref(ref: str) -> str:
-	"""
-	Validate if the provided string is a valid Git reference.
-
-	Args:
-		ref (str) -- The Git reference to validate.
-
-	Returns:
-		str -- The validated Git reference.
-
-	Raises:
-		ValueError -- If the reference contains invalid characters.
-
-	Meta-Testing:
-
-		Testcase 1: Valid reference.
-
-			>>> _validate_git_ref('main')
-			'main'
-
-		Testcase 2: Valid reference with special characters.
-
-			>>> _validate_git_ref('feature/new-feature')
-			'feature/new-feature'
-
-		Testcase 3: Invalid reference with disallowed characters.
-
-			>>> _validate_git_ref('invalid$ref')  #doctest: +IGNORE_EXCEPTION_DETAIL +ELLIPSIS
-			Traceback (most recent call last):
-			...
-			ValueError: Invalid Git reference: invalid$ref
-
-		Testcase 4: Empty reference.
-
-			>>> _validate_git_ref('')  #doctest: +IGNORE_EXCEPTION_DETAIL +ELLIPSIS
-			Traceback (most recent call last):
-			...
-			ValueError: Invalid Git reference:...
-	"""
-	if not re.match(r'^[a-zA-Z0-9_\-./]+$', ref):
-		raise ValueError(f"Invalid Git reference: {ref}")
-	return ref
 
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath(""".."""))
+from docs.utils import _validate_git_ref
+from docs.utils import slugify_header
 
 # Define the branch reference for linkcode_resolve
 DOCS_BUILD_REF: str = _validate_git_ref(os.environ.get("DOCS_BUILD_REF", "stable"))
@@ -98,10 +59,6 @@ def _validate_git_ref(ref: str) -> str:
 		variable is not set.
 """
 
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath(""".."""))
 sys.path.insert(1, os.path.abspath("""multicast"""))
 sys.path.insert(1, os.path.abspath("""tests"""))
 
@@ -116,7 +73,7 @@ def _validate_git_ref(ref: str) -> str:
 # for rst use 'sphinx.ext.autodoc'
 extensions = [
 	"""sphinx.ext.napoleon""", """autodoc2""", """sphinx.ext.autosectionlabel""",
-	"""sphinx.ext.githubpages""", """myst_parser""",
+	"""sphinx.ext.githubpages""", """myst_parser""", """sphinx_design""",
 	"""sphinx.ext.autosummary""", """sphinx.ext.doctest""", """sphinx.ext.todo""",
 	"""sphinx.ext.linkcode""", """sphinx.ext.viewcode""", """sphinx.ext.intersphinx""",
 ]
@@ -321,19 +278,46 @@ def _validate_git_ref(ref: str) -> str:
 # see https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html
 
 # be more like GFM with style
-myst_enable_extensions = ("tasklist", "strikethrough", "fieldlist")
+myst_enable_extensions = ("tasklist", "strikethrough", "fieldlist", "linkify")
 
 # for GFM diagrams and interoperability with other Markdown renderers
 myst_fence_as_directive = ("mermaid", "suggestion", "note")
 
+# Add linkify configuration
+myst_linkify_fuzzy_links = False
+
 # Focus only on github markdown
-# myst_gfm_only = True
+myst_gfm_only = True
+
+myst_html_meta = {
+	"github_url": f"https://github.com/reactive-firewall/{project}"
+}
+
+# For GH-style admonitions to MyST conversion
+myst_admonition_aliases = {
+	"note": "note",
+	"warning": "warning",
+	"important": "important",
+	"tip": "tip",
+	"caution": "caution"
+}
 
 # how deep should markdown headers have anchors be generated
 heading_anchors = 3
 
+# Enable header anchors as requested
+myst_heading_anchors = 3
+
+# For better slug generation in header references
+myst_heading_slug_func = slugify_header
+
 # -- Options for napoleon ext --------------------------------------------------
 
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = False
+
 # include __init__ when it has docstrings
 napoleon_include_init_with_doc = True
 
@@ -432,9 +416,7 @@ def _validate_git_ref(ref: str) -> str:
 
 # -- Link resolver -------------------------------------------------------------
 
-linkcode_url_prefix: str = str(
-	"""https://github.com/reactive-firewall/{proj}"""
-).format(proj=project)
+linkcode_url_prefix: str = f"https://github.com/reactive-firewall/{project}"
 
 extlinks = {
 	"""issue""": (

docs/requirements.txt

@@ -36,10 +36,12 @@ pip>=24.3.1
 # build - MIT license
 build>=1.2.1, !=1.2.2.post1
 # sphinx - BSD license
-sphinx>=7.0
+sphinx>=7.3
 # sphinx-autodoc2 - MIT license
 sphinx-autodoc2>=0.5.0
 # myst-parser - MIT license
 myst-parser[linkify]>=4.0.0
 # sphinxawesome-theme - MIT license
 sphinxawesome-theme>=5.2
+# sphinx_design - BSD license
+sphinx_design>=0.6.1

docs/utils.py

@@ -0,0 +1,109 @@
+# -*- coding: utf-8 -*-
+
+# Multicast Documentation Utilities
+# ..................................
+# Copyright (c) 2024-2025, Mr. Walls
+# ..................................
+# Licensed under MIT (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# ..........................................
+# https://www.github.com/reactive-firewall/multicast/LICENSE.md
+# ..........................................
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import re
+
+def _validate_git_ref(ref: str) -> str:
+	"""
+	Validate if the provided string is a valid Git reference.
+
+	Args:
+		ref (str) -- The Git reference to validate.
+
+	Returns:
+		str -- The validated Git reference.
+
+	Raises:
+		ValueError -- If the reference contains invalid characters.
+
+	Meta-Testing:
+
+		Testcase 1: Valid reference.
+
+			>>> _validate_git_ref('main')
+			'main'
+
+		Testcase 2: Valid reference with special characters.
+
+			>>> _validate_git_ref('feature/new-feature')
+			'feature/new-feature'
+
+		Testcase 3: Invalid reference with disallowed characters.
+
+			>>> _validate_git_ref('invalid$ref')  #doctest: +IGNORE_EXCEPTION_DETAIL +ELLIPSIS
+			Traceback (most recent call last):
+			...
+			ValueError: Invalid Git reference: invalid$ref
+
+		Testcase 4: Empty reference.
+
+			>>> _validate_git_ref('')  #doctest: +IGNORE_EXCEPTION_DETAIL +ELLIPSIS
+			Traceback (most recent call last):
+			...
+			ValueError: Invalid Git reference:...
+	"""
+	if not re.match(r'^[a-zA-Z0-9_\-./]+$', ref):
+		raise ValueError(f"Invalid Git reference: {ref}")
+	return ref
+
+
+def slugify_header(s: str) -> str:
+	"""
+	Convert header text to a URL-friendly slug.
+
+	This function transforms header text into a URL-friendly slug by removing special characters,
+	converting to lowercase, and replacing consecutive spaces or dashes with a single dash.
+	The resulting slug is suitable for use in header anchors and URL paths.
+
+	Arguments:
+		s (str) -- The header text to be converted into a slug.
+
+	Returns:
+		str -- A URL-friendly slug derived from the input text.
+
+	Unit-Testing:
+
+		Testcase 1: Basic header with spaces and special characters.
+
+			>>> slugify_header("Hello, World!")
+			'hello-world'
+
+		Testcase 2: Header with multiple spaces and mixed case.
+
+			>>> slugify_header("  API   Documentation  ")
+			'api-documentation'
+
+		Testcase 3: Header with consecutive spaces and dashes.
+
+			>>> slugify_header("API -- Documentation")
+			'api-documentation'
+
+		Testcase 4: Header with Unicode characters and accents.
+
+			>>> slugify_header("über café 123")
+			'über-café-123'
+
+		Testcase 5: Header with special markdown characters.
+
+			>>> slugify_header("[CEP-7] Documentation *Guide*")
+			'cep-7-documentation-guide'
+	"""
+	# First, remove special characters and convert to lowercase
+	text = re.sub(r'[^\w\- ]', '', s).strip().lower()
+	# Then replace consecutive spaces or dashes with a single dash
+	return re.sub(r'[-\s]+', '-', text)

pyproject.toml

@@ -2,6 +2,25 @@
 requires = ["setuptools>=75.0", "build>=1.2.1", "wheel>=0.44"]
 build-backend = "setuptools.build_meta"
 
+[tool.flake8]
+# OPTIONAL - BCP selection
+# select = ["C", "E", "F", "W", "B", "B950"]
+# CEP-7 specific
+extend-select = ["D", "E"]
+# OPTIONAL - BCP Ignore specific warnings and errors according to CEP-8 style
+# ignore = ["W191", "W391", "E117"]
+# Ignore specific warnings and errors according to CEP-7 style
+extend-ignore = ["E117", "D203", "D208", "D212"]
+# REQUIRED CEP-7 Custom Exceptions:
+#    E117,  # Over-indented - RECCOMENDED
+#    D208,  # Docstring is over-indented - CEP-7
+#    D203,  # 1 blank line required before class docstring - CEP-7
+#    D212,  # Multi-line docstring summary should start at the first line - CEP-7
+# OPTIONAL - BCP Ignore long lines as specified in CEP-8
+max-line-length = 100
+docstring-convention = "google"
+docstring_style = "google"
+
 [pytest.enabler.flake8]
 addopts = "--flake8"