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
```
