Metadata-Version: 2.4
Name: sphinx-doclang
Version: 26.8.30
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: Documentation, https://kmcasi.github.io/sphinx-doclang/
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: Framework :: Sphinx
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
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

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 `text_color`, `font_size` or `font_name`
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*.
- **Templates** ➜ Eliminate repetitive content for a specific object name or type.

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 some preview for what you need for this Sphinx configuration:

```python
extensions = [
    "sphinx.ext.autodoc",           # required: pull in docstrings from code
    ...,
    "sphinx_doclang"                # DSL for documentation language
]
```

### Example of usage

DocLang commands can be used directly inside docstrings:

```python
class Example:
    """
    A simple example class.

    § 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
# Marks the beginning of a DocLang command.
doclang_command_start = "§"

# Marks the end of a DocLang command.
doclang_command_end = "¶"

# Separate the command name from its arguments.
doclang_command_splitter = ":"

# Separate multiple arguments inside a command.
# Each character acts as an independent argument separator.
doclang_argument_separator = ",;"

# Separate keywords from their assigned values.
doclang_keyword_separator = "="

# Marks comments inside DocLang command blocks.
# Each character acts as an independent comment marker.
doclang_comment_marker = "#"

# Characters used to escape DocLang syntax when literal text is required.
# Each character acts as an independent escape marker.
doclang_escape_marker = "/|"

# Whether unknown/unregistered commands should be preserved instead of removed.
doclang_keep_unknown = False

# Whether commands validation should be performed.
doclang_validate_command = True
```
