Metadata-Version: 2.4
Name: sphinx-github-alerts
Version: 1.0
Summary: This Sphinx extension converts GitHub alerts to Sphinx admonitions.
Author-email: Dennis den Ouden-van der Horst <d.denouden-vanderhorst@tudelft.nl>
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: sphinx
Description-Content-Type: text/markdown

# Sphinx GitHub Alerts

## Introduction

This Sphinx extension converts GitHub alerts to Sphinx admonitions.

## What does it do?

This extension allows you to use [GitHub alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) within your Sphinx project.

Only top-level alerts are allowed and are convert to a top-level admonition in the language (`MD` or `rST`) of the source file. The source file does not change.

Nesting is not supported.

If an alert is not recognised, a warning is returned.

## Installation

To use this extension, follow these steps:

**Step 1: Install the Package**

Install the module `sphinx-github-alerts` package using `pip`:
```
pip install sphinx-github-alerts
```
    
**Step 2: Add to `requirements.txt`**

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

**Step 3: Enable in `_config.yml` or `conf.py`**

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

or in your `conf.py` file, add the extension to the `extensions` list and specify the location of your bib file:

```python
extensions = [...,"sphinx_apa_references",...]
```

## Configuration

The extension provides several configuration values, which can be added to your configuration file:

- `sphinx_github_alerts_backquotes`: `3` (_default_) or `integer`: (only relevant for MarkDown based files) The number of backticks used to start and end the admonitions. Should be at minimum 3.
- `sphinx_github_alerts_leading_spaces`: `3` (_default_) or `integer`: (only relevant for reStructeredText based files) The number of spaces for indentation within the admonitions. Should be at minimum 1.
- `sphinx_github_alerts_redirects`: `{}`  (_default_) or `dict`: Every _key_-**value** pair in this dictionary redirects the GitHub alert indicated by _key_ to the Sphinx admonition indicated by **value**.

## Examples

For each of the five GitHub alerts, you can see the result below. Note that the result depends on where you are visiting this page.

The codes contain a leading space to enforce showing the code and not converting the code. In any application these leading spaces should not be present.

### Note

```
 > [!NOTE]
 > Useful information that users should know, even when skimming content.
```

> [!NOTE]
> Useful information that users should know, even when skimming content.

### Tip

```
 > [!TIP]
 > Helpful advice for doing things better or more easily.
```

> [!TIP]
> Helpful advice for doing things better or more easily.

### Important

```
 > [!IMPORTANT]
 > Key information users need to know to achieve their goal.
```

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

### Warning

```
 > [!WARNING]
 > Urgent info that needs immediate user attention to avoid problems.
```

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

### Caution

```
 > [!CAUTION]
 > Advises about risks or negative outcomes of certain actions.
 >
 > But multiline alerts can also be used.
```

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.
>
> But multiline alerts can also be used.
