Metadata-Version: 2.4
Name: sphinx-gated-directives
Version: 1.0.1
Summary: This package is an extension for Sphinx that creates a '-start' companion and a '-end' companion for every registered class-based directive.
Author-email: Dennis den Ouden-van der Horst <d.denouden-vanderhorst@tudelft.nl>
License: MIT License
        
        Copyright (c) 2025 TeachBooks
        
        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.
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: sphinx
Description-Content-Type: text/markdown

# Sphinx Gated Directives
<!-- Start content -->
This package is an extension for Sphinx that creates a start directive and an end directive for every registered class-based directive.

## What does it do?

This extension performs the following steps:
1. It scans the Sphinx environment for all registered class-based directives.
2. For each directive found, it automatically registers two new directives:
   - A **start** directive that marks the beginning of a block.
   - An **end** directive that marks the end of a block.
3. On build time, it processes these start and end directives to ensure that content between them is handled correctly.

For example, if you have a directive called `warning`, this extension will create (with _default settings_) two new directives: `warning-start` and `warning-end`. The code:

```markdown
:::{warning}
This is a warning message.

So, be careful!
:::
```

can now be replaced with the code

```markdown
:::{warning-start}
This is a warning message.
:::

So, be careful!

:::{warning-end}
:::
```

In short:
- This extension splits the original directive into a start and end directive.
- The start directive has the same options as the original directive.
- Anything inside the start directive is processed as usual.
- Anything between the start and end directives is processed as usual, and then added to the output of the start directive.
- The end directive is mandatory to close the directive.
- Anything inside the end directive is ignored.

This allows two things:
1. More granular control over where the directive starts and ends, which can be useful in complex documents. This is similar to how HTML tags and LaTeX environments work.
2. The ability to nest directives more easily, as the start and end markers can be placed independently. A major benefit of this is that it allows for nesting of code-cells.

<!-- Start caution -->

> [!CAUTION]
> Some directives parse the content inside the directive. If that content is moved between the start and end directives, it may not be parsed as expected, as it will be parsed separately. Please see to the [Examples](#examples) section for more details.

<!-- End caution -->

## Installation
To use this extension, follow these steps:

**Step 1: Install the Package**

Install the module `sphinx-gated-directives` package using `pip`:

```
pip install sphinx-gated-directives
```
    
**Step 2: Add to `requirements.txt`**

Make sure that the package is included in your project's `requirements.txt` to track the dependency:

```
sphinx-gated-directives
```

**Step 3: Enable in `_config.yml`**

In your `_config.yml` file, add the extension to the list of Sphinx extra extensions (**important**: underscore, not dash this time):

```yaml
sphinx: 
    extra_extensions:
        .
        .
        .
        - sphinx_gated_directives
        .
        .
        .
```

or similarly in your `conf.py` file.

## Configuration

This extension can be configured via the `_config.yml` file in your JupyterBook project (or similarly in `conf.py` for standard Sphinx projects).

The default configuration options are as follows:

```yaml
sphinx:
  config:
    sphinx_gated_directives:
      suffix_start: start    # Suffix for the start directive
      suffix_end: end        # Suffix for the end directive
      suffix_separator: '-'     # Separator between the original directive name and the suffix
      override_existing: false  # Whether to override existing gated directives with the same name
```

Per key the meanings are:
- `suffix_start`: The suffix to append to the original directive name for the start directive.
  - Default is `start`.
  - Must be a non-empty string containing only `a-z`.
- `suffix_end`: The suffix to append to the original directive name for the end directive.
  - Default is `end`.
  - Must be a non-empty string containing only `a-z`.
- `suffix_separator`: The separator to use between the original directive name and the suffix.
  - Default is `-`.
  - Must be a single character, no space, no underscore, no colon, or empty string.
- `override_existing`: Whether to override existing gated directives with the same name.
  - Default is `false`.
  - Must be a boolean value (`true` or `false`), a single string or a list of strings.
  - If `false`, none existing gated directives will be overridden.
  - If `true`, all existing gated directives will be overridden.
  - If a string or a list of strings, only the existing gated directives with names in the list/string will be overridden.

<!-- End configuration -->


> [!WARNING]
> Setting `override_existing` to anything other than `false` may lead to unexpected behavior if those directives are already in use.
> 
> Use with caution.

## Examples

Examples for this extension is available in the [TeachBooks manual](https://teachbooks.io/manual/_git/github.com_TeachBooks_Sphinx-Gated-Directives/main/MANUAL.html).

<!-- Start contribute -->
## Contribute

This tool's repository is stored on [GitHub](https://github.com/TeachBooks/Sphinx-Gated-Directives). If you'd like to contribute, you can create a fork and open a pull request on the [GitHub repository](https://github.com/TeachBooks/Sphinx-Gated-Directives).
