sphinx-doclang 26.7.8__tar.gz

sphinx_doclang-26.7.8/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Afanase Ioan (ASI)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sphinx_doclang-26.7.8/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: sphinx-doclang
+Version: 26.7.8
+Summary: Sphinx extension providing the custom DSL for generating structured documentation blocks.
+Author: ASI
+License: MIT License
+        
+        Copyright (c) 2026 Afanase Ioan (ASI)
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Source, https://github.com/kmcasi/sphinx-doclang
+Project-URL: Issues, https://github.com/kmcasi/sphinx-doclang/issues
+Keywords: sphinx,extension,dsl,doclang,documentation,autodoc,command
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Framework :: Sphinx
+Classifier: Framework :: Sphinx :: Extension
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Documentation
+Classifier: Topic :: Documentation :: Sphinx
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: Sphinx>=9.1.0
+
+# Doc Lang – Sphinx extension
+
+## Sphinx Documentation Language Extension with Custom Commands and Templates
+
+This Sphinx extension introduces **DocLang**, a lightweight domain‑specific language designed to generate structured, 
+expressive and automation‑friendly documentation blocks inside Python docstrings.
+
+## Why DocLang Exists
+
+DocLang began as a simple keyword replacer — a lightweight way to inject small
+pieces of text into docstrings. Over time, it evolved into a flexible inline
+command system with templates, introspection, and automation features. Despite
+this growth, the core idea has remained the same:
+
+**DocLang helps automate repetitive parts of documentation.**
+
+Most projects contain patterns that repeat across multiple classes. In UI/UX
+libraries, this is especially common: attributes such as `background`,
+`background_color`, `text_color`, `font_size`, `font_name` or `font_family`
+appear in many widgets and their descriptions often differ only by a few words.
+DocLang allows you to define custom commands and templates that encapsulate these
+repetitive descriptions, letting you focus on the actual implementation instead
+of rewriting boilerplate documentation.
+
+The same applies to event systems. For example, in a button or other behavior
+class, events often follow predictable naming and implementation patterns. With
+DocLang, you can create a command that scan a class for events, locate
+their implementations, extract the docstring descriptions and automatically
+generate an event list at the top of the page. This means you can add or remove
+events without worrying about manually updating the documentation — DocLang
+handles it for you.
+
+DocLang is designed to be extended. Users are encouraged to define their own
+commands based on the needs of their project, creating a documentation workflow
+that is both expressive and maintainable.
+
+---
+
+## Features
+
+- **New commands**: Creating custom commands.
+- **Overwrite commands**: Override existing commands with your own implementations.
+- **Default commands**: Simple built‑in commands for generating *delimiters*, *titles*, *sections*, and *lists*.
+- **Self‑introspection commands**: Retrieve the object's *name*, *type*, *documentation*, and *signature*.
+- Fully compatible with **Sphinx autodoc**
+- Zero configuration required beyond enabling the extension
+
+DocLang is designed to keep your docstrings readable while producing rich, structured documentation output.
+
+---
+
+## Requirements
+
+- **Python** • ***3.12+***
+- **Sphinx** • ***9.1.0+***
+
+---
+
+## Installation
+
+```bash
+pip install sphinx-doclang
+```
+
+---
+
+## Usage
+
+### Enable the extension
+In your `conf.py`, add the extension to the `extensions` list.  
+Below is an example of a typical Sphinx configuration:
+
+```python
+extensions = [
+    "sphinx.ext.autodoc",           # pull in docstrings from code
+    "sphinx.ext.autosummary",       # generate summary/API pages
+    "sphinx.ext.napoleon",          # support Google/NumPy-style docstrings
+    "sphinx.ext.intersphinx",       # link to external docs (Kivy, Python, etc.)
+    "sphinx.ext.todo",              # support for exposing todo notes
+    
+    "sphinx_localtoc",              # stylizing the local ToC
+    "sphinx_doclang"                # DSL for documentation language
+]
+```
+
+### Example of usage
+
+DocLang commands can be used directly inside docstrings:
+
+```python
+class Example:
+    """
+    A simple example class.
+	
+    § list : First item, Second item, Third item ¶
+
+    § section : debug purpose only, style = camel ¶
+
+    § debug object ¶
+    """
+```
+
+DocLang commands always begin with ```§ command : arguments ¶```. 
+The DSL is intentionally minimal and easy to read inside source code.
+
+---
+
+### Configuration options
+
+The extension provides the following configuration variables, shown here with their default values:
+
+```python
+# Character that marks the beginning of a DocLang command.
+doclang_command_start = "§"
+
+# Character that marks the end of a DocLang command.
+doclang_command_end = "¶"
+
+# Character used to separate the command name from its arguments.
+doclang_command_splitter = ":"
+
+# Characters used to separate multiple arguments inside a command.
+# Each character acts as a valid separator.
+doclang_argument_separator = ",;"
+
+# Character used to separate keywords from their assigned values.
+doclang_keyword_separator = "="
+
+# Character used to mark comments inside DocLang command blocks.
+doclang_comment_marker = "#"
+
+# Characters used to escape DocLang syntax when literal text is required.
+# Each character acts as a valid escaper.
+doclang_escape_marker = "/|"
+
+# Whether unknown or unregistered commands should be preserved instead of removed.
+doclang_keep_unknown = False
+```

sphinx_doclang-26.7.8/README.md

@@ -0,0 +1,138 @@
+# Doc Lang – Sphinx extension
+
+## Sphinx Documentation Language Extension with Custom Commands and Templates
+
+This Sphinx extension introduces **DocLang**, a lightweight domain‑specific language designed to generate structured, 
+expressive and automation‑friendly documentation blocks inside Python docstrings.
+
+## Why DocLang Exists
+
+DocLang began as a simple keyword replacer — a lightweight way to inject small
+pieces of text into docstrings. Over time, it evolved into a flexible inline
+command system with templates, introspection, and automation features. Despite
+this growth, the core idea has remained the same:
+
+**DocLang helps automate repetitive parts of documentation.**
+
+Most projects contain patterns that repeat across multiple classes. In UI/UX
+libraries, this is especially common: attributes such as `background`,
+`background_color`, `text_color`, `font_size`, `font_name` or `font_family`
+appear in many widgets and their descriptions often differ only by a few words.
+DocLang allows you to define custom commands and templates that encapsulate these
+repetitive descriptions, letting you focus on the actual implementation instead
+of rewriting boilerplate documentation.
+
+The same applies to event systems. For example, in a button or other behavior
+class, events often follow predictable naming and implementation patterns. With
+DocLang, you can create a command that scan a class for events, locate
+their implementations, extract the docstring descriptions and automatically
+generate an event list at the top of the page. This means you can add or remove
+events without worrying about manually updating the documentation — DocLang
+handles it for you.
+
+DocLang is designed to be extended. Users are encouraged to define their own
+commands based on the needs of their project, creating a documentation workflow
+that is both expressive and maintainable.
+
+---
+
+## Features
+
+- **New commands**: Creating custom commands.
+- **Overwrite commands**: Override existing commands with your own implementations.
+- **Default commands**: Simple built‑in commands for generating *delimiters*, *titles*, *sections*, and *lists*.
+- **Self‑introspection commands**: Retrieve the object's *name*, *type*, *documentation*, and *signature*.
+- Fully compatible with **Sphinx autodoc**
+- Zero configuration required beyond enabling the extension
+
+DocLang is designed to keep your docstrings readable while producing rich, structured documentation output.
+
+---
+
+## Requirements
+
+- **Python** • ***3.12+***
+- **Sphinx** • ***9.1.0+***
+
+---
+
+## Installation
+
+```bash
+pip install sphinx-doclang
+```
+
+---
+
+## Usage
+
+### Enable the extension
+In your `conf.py`, add the extension to the `extensions` list.  
+Below is an example of a typical Sphinx configuration:
+
+```python
+extensions = [
+    "sphinx.ext.autodoc",           # pull in docstrings from code
+    "sphinx.ext.autosummary",       # generate summary/API pages
+    "sphinx.ext.napoleon",          # support Google/NumPy-style docstrings
+    "sphinx.ext.intersphinx",       # link to external docs (Kivy, Python, etc.)
+    "sphinx.ext.todo",              # support for exposing todo notes
+    
+    "sphinx_localtoc",              # stylizing the local ToC
+    "sphinx_doclang"                # DSL for documentation language
+]
+```
+
+### Example of usage
+
+DocLang commands can be used directly inside docstrings:
+
+```python
+class Example:
+    """
+    A simple example class.
+	
+    § list : First item, Second item, Third item ¶
+
+    § section : debug purpose only, style = camel ¶
+
+    § debug object ¶
+    """
+```
+
+DocLang commands always begin with ```§ command : arguments ¶```. 
+The DSL is intentionally minimal and easy to read inside source code.
+
+---
+
+### Configuration options
+
+The extension provides the following configuration variables, shown here with their default values:
+
+```python
+# Character that marks the beginning of a DocLang command.
+doclang_command_start = "§"
+
+# Character that marks the end of a DocLang command.
+doclang_command_end = "¶"
+
+# Character used to separate the command name from its arguments.
+doclang_command_splitter = ":"
+
+# Characters used to separate multiple arguments inside a command.
+# Each character acts as a valid separator.
+doclang_argument_separator = ",;"
+
+# Character used to separate keywords from their assigned values.
+doclang_keyword_separator = "="
+
+# Character used to mark comments inside DocLang command blocks.
+doclang_comment_marker = "#"
+
+# Characters used to escape DocLang syntax when literal text is required.
+# Each character acts as a valid escaper.
+doclang_escape_marker = "/|"
+
+# Whether unknown or unregistered commands should be preserved instead of removed.
+doclang_keep_unknown = False
+```

sphinx_doclang-26.7.8/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sphinx-doclang"
+version = "26.7.8"
+description = "Sphinx extension providing the custom DSL for generating structured documentation blocks."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { file = "LICENSE" }
+authors = [{ name = "ASI" }]
+keywords = [
+	"sphinx",
+	"extension",
+	"dsl",
+	"doclang",
+	"documentation",
+	"autodoc",
+	"command"
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "License :: OSI Approved :: MIT License",
+  "Framework :: Sphinx",
+  "Framework :: Sphinx :: Extension",
+  "Intended Audience :: Developers",
+  "Topic :: Documentation",
+  "Topic :: Documentation :: Sphinx",
+  "Topic :: Software Development :: Documentation",
+]
+dependencies = [
+    "Sphinx>=9.1.0",
+]
+
+[project.urls]
+Source = "https://github.com/kmcasi/sphinx-doclang"
+Issues = "https://github.com/kmcasi/sphinx-doclang/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+license-files = []
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]

sphinx_doclang-26.7.8/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sphinx_doclang-26.7.8/src/sphinx_doclang/__init__.py

@@ -0,0 +1,31 @@
+#//|>-----------------------------------------------------------------------------------------------------------------<|
+#//| Copyright (c) 15 Feb 2026. All rights are reserved by ASI
+#//|>-----------------------------------------------------------------------------------------------------------------<|
+
+#// IMPORT
+# from importlib.resources import files
+from sphinx.application import Sphinx
+from sphinx.util.typing import ExtensionMetadata
+
+from ._version import VERSION_STRING
+from .processor import setup_processor, validate_command_configuration_values
+from .manager import TemplateManager
+
+
+#// RUN
+def setup(app: Sphinx) -> ExtensionMetadata:
+    # root = files(__name__)
+    # app.config.html_static_path.append(str(root / "_static"))
+    # app.add_css_file("styles/localtoc.css")
+
+    setup_processor(app)
+
+    validate_command_configuration_values(app)
+
+    TemplateManager._init_app(app)
+
+    return {
+        "version": VERSION_STRING,
+        "parallel_read_safe": True,
+        "parallel_write_safe": False,
+    }

sphinx_doclang-26.7.8/src/sphinx_doclang/_version.py

@@ -0,0 +1,32 @@
+#//|>-----------------------------------------------------------------------------------------------------------------<|
+#//| Copyright (c) 15 Feb 2026. All rights are reserved by ASI
+#//|>-----------------------------------------------------------------------------------------------------------------<|
+__all__ = (
+    "MAJOR", "MINOR", "MICRO", "REVISION",
+    "S_STABLE", "VERSION_STRING"
+)
+
+#//| Version variables
+#//|>--------------------------------------------------------<|
+MAJOR: int = 26
+MINOR: int = 7
+MICRO: int = 8
+VERSION_STRING: str = f"{MAJOR}.{MINOR}.{MICRO}"
+
+
+#//| Development | Revision
+#//|>--------------------------------------------------------<|
+REVISION: int = 0
+S_STABLE: bool = True
+
+# If is not a stable state, update `VERSION_STRING` to reflect that
+if not S_STABLE:
+    VERSION_STRING = f"{VERSION_STRING}.dev{max(1, REVISION)}"
+elif REVISION > 0:
+    VERSION_STRING = f"{VERSION_STRING}.rev{REVISION}"
+
+
+#//| exec'd
+#//|>--------------------------------------------------------<|
+__version__: str = VERSION_STRING
+

sphinx_doclang-26.7.8/src/sphinx_doclang/error.py

@@ -0,0 +1,62 @@
+#//|>-----------------------------------------------------------------------------------------------------------------<|
+#//| Copyright (c) 18 Feb 2026. All rights are reserved by ASI
+#//|>-----------------------------------------------------------------------------------------------------------------<|
+__all__ = ("DocLangError","InvalidCommandError","InvalidConfigError")
+
+
+#// LOGIC
+class DocLangError(Exception):
+    """Base exception for all DocLang‑related errors."""
+
+    def __init__(self, message: str, *args) -> None:
+        super().__init__(f"[DocLang Error] {message}", *args)
+
+    def note(self, title: str, message: str|list[str], indent: int = 0) -> None:
+        """
+        Attach a formatted note to the current error.
+
+        Notes provide additional context, suggestions or multi‑line guidance
+        that appears alongside the main error message in Sphinx output.
+
+        :param title:   A short label describing the purpose of the note.
+        :param message: Either a single string or a list of strings.
+        :param indent:  Number of spaces to indent multi‑line messages.
+
+        :return: Nothing.
+        """
+        # Local variables
+        formatted: str = ""
+
+        # Single-line message
+        if isinstance(message, str):
+            formatted = message
+
+        else:
+            # One-line list ➜ treat as a normal string
+            if len(message) == 1:
+                formatted = message[0]
+
+            # Multi-line list ➜ format with indentation
+            else:
+                prefix: str = f"\n\t{' ' * (len(title) + 3 + indent)}"
+
+                for message_index in range(len(message)):
+                    formatted = f"{formatted}{prefix if message_index else ''}{message[message_index]}"
+
+        # Only add the note if the message contains meaningful content
+        if formatted.strip():
+            self.add_note(f"\t[{title}] {formatted}")
+
+
+class InvalidCommandError(DocLangError):
+    """Raised when a DSL command is invalid or cannot be registered."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+class InvalidConfigError(DocLangError):
+    """Raised when attempting to use a configuration value with an invalid signature."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)