Configuration❖

Overview❖

DocLang provides several configuration variables that control how commands are detected, parsed and interpreted. This page describes each option and explains the syntax rules that depend on them.

All configuration variables are optional. If not specified, DocLang uses the default values shown below.

Variables❖

The following variables can be added to your conf.py file:

# 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

Syntax Rules❖

DocLang commands follow a simple pattern based on the configuration variables defined above. Understanding these rules will help you write correct and predictable command blocks inside your docstrings.

The sections below explain how each part of the syntax works.

Important

When customizing any syntax, be careful to avoid reusing characters. Even if the sequences appear visually distinct, DocLang checks each character individually. If any character is used more than once across all delimiters, splitters, separators or markers, DocLang will raise an InvalidConfigError.

Invalid configuration example❖

doclang_command_start = "<<"
doclang_command_end = ">>"
doclang_command_splitter = ">:<"

Usage❖

<< title >:< example splitter >>

Terminal output❖

Traceback
=========

      File "E:\Python\PublicWork\sphinx-doclang\sphinx_doclang\processor.py", line 399, in validate_command_configuration_values
        raise error
    sphinx_doclang.error.InvalidConfigError: [DocLang Error] The character '>' in 'doclang_command_splitter' is already used in 'doclang_command_end'.
        [Suggestion] Use distinct characters across all command tags, separators and markers.

Command Delimiters❖

Configuration variables❖

# Marks the beginning of a DocLang command.
doclang_command_start = "§"

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

A command is always wrapped between the start and end markers:

§ command ¶

Example❖

§ debug object ¶

Command Splitter❖

Configuration variable❖

# Characters used to separate the command name from its arguments.
doclang_command_splitter = ":"

Most commands require one or more arguments. The splitter separates the command name from its arguments:

§ command : arguments ¶

Example❖

§ title : example command ¶

Argument Separator❖

Configuration variables❖

# Characters used to separate multiple arguments inside a command.
# Each character acts as a valid separator.
doclang_argument_separator = ",;"

Multiple arguments inside a command can be separated using any of the characters defined in doclang_argument_separator. Each character is interpreted as an independent separator.

Example❖

§ list : width, height; depth ¶

Keyword Separator❖

Configuration variable❖

# Character used to separate keywords from their assigned values.
doclang_keyword_separator = "="

Some commands support keyword/value pairs. The keyword separator defines the character used to assign a value to a keyword inside the argument block.

Example❖

§ section : title = overview ¶

In this example, title is the keyword and Overview is the assigned value. The keyword separator = makes the relationship explicit and easy to parse.

Comments❖

Configuration variable❖

# Character used to mark comments inside DocLang command blocks.
doclang_comment_marker = "#"

DocLang allows comments inside command blocks. A comment begins with the configured marker and continues until the end of the command block. Comments are ignored during processing and do not affect the command output.

Example❖

§ list : item 1, item 2, # item 3 ¶

In this example, everything after # is treated as a comment and removed before the command is evaluated.

Escaping❖

Configuration variable❖

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

DocLang provides an escape mechanism for situations where you need to include characters that would normally be interpreted as part of a command. Any character defined in doclang_escape_marker can be used to escape DocLang syntax, allowing literal text to appear inside command blocks.

Example❖

§ list : item 1, item 2/, item 3|, item 4 ¶

In this example, the last two commas are treated as literal text because they are prefixed with escape markers.

Unknown Commands❖

Configuration variable❖

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

By default, DocLang removes any command that is not registered or recognized by the processor. This ensures that accidental typos, incomplete commands or unsupported syntax do not appear in the generated documentation.

Example (default behavior)❖

One § unknown command ¶ is here

Output❖

One is here

Validate Commands❖

Configuration variable❖

# Whether commands validation should be performed.
doclang_validate_command = True

When this option is enabled, DocLang validates every command before it is registered or overwritten. The validation step ensures that the command can safely accept any number of arguments. If the command defines a return type hint and supports multiple arguments, it is considered valid immediately. Otherwise, DocLang simulates a call with a large number of arguments (up to 100) to verify that the implementation does not break when users provide more arguments than expected.

This mechanism ensures that all commands behave consistently inside the DSL, where arguments are always passed as plain strings and the number of arguments cannot be restricted.