Metadata-Version: 2.4
Name: sphinx-indexed-definitions
Version: 1.0.2
Summary: A Sphinx extension that fills the index based on definitions in a Sphinx book
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
Requires-Dist: sphinx-proof
Description-Content-Type: text/markdown

# Sphinx Indexed Definitions

## Introduction

This Sphinx extension provides an easy way to add entries to a genreated index based on **strong**, *emphasized* and/or `literal` terms used within `prf:definition` admonitions and the title of the adminition.

## What does it do?

If you code includes an admonition with the source code

```md
:::{prf:definition} Lorem
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse **Pharetra**, ex ut commodo varius,
est justo vestibulum nunc, *(id) dignissim* lorem nibh in mauris. Duis varius lorem et neque posuere,
ac elementum eros consequat. Maecenas sed risus suscipit, **fermentum Kelvin** quam vitae, consectetur
augue. Maecenas aliquam leo vitae velit interdum efficitur.
:::
```

this extension, once loaded, will add (with default settings) the terms Lorem, **pharetra**, *id dignissim*, *dignissim* and **fermentum Kelvin** to the generated index.

This extension can be used in conjunction with the regular usage of generating an index, as explained at [Indexes](https://jupyterbook.org/en/stable/content/content-blocks.html#indexes).

## Installation
To use this extenstion, follow these steps (be aware, more steps then usual):

**Step 1: Install the Package**

Install the module `sphinx-indexed-definitions` package using `pip`:
```
pip install git+https://github.com/TeachBooks/Sphinx-Indexed-Definitions.git
```
    
**Step 2: Add to `requirements.txt`**

Make sure that the package is included in your project's `requirements.txt` to track the dependency:
```
git+https://github.com/TeachBooks/Sphinx-Indexed-Definitions.git
```

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

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

**Step 4: Add the general index to ToC**

To do this, if you have not done this, please follow the instructions at [Add the general index to your table of contents](https://jupyterbook.org/en/stable/content/content-blocks.html#add-the-general-index-to-your-table-of-contents).

## Configuration

The extension provides several configuration values, which can be added to `_config.yml` if the default value should be changed:

```yaml
sphinx: 
    config:
        -
        -
        -
        sphinx_indexed_defs_indexed_nodes:     ['strong','emphasis'] # default value
        sphinx_indexed_defs_skip_indices:      []                    # default value
        sphinx_indexed_defs_lowercase_indices: true                  # default value
        sphinx_indexed_defs_index_titles:      true                  # default value
        sphinx_indexed_defs_capital_words:     []                    # default value
        sphinx_indexed_defs_remove_brackets:   true                  # default value
        sphinx_indexed_defs_force_main:        true                  # default value
        sphinx_indexed_defs_index_theorems:    true                  # default value
        -
        -
        -
```

- `sphinx_indexed_defs_indexed_nodes`: `['strong','emphasis']` (_default_) or **list of strings**:
  - All nodes of the provided classes from the Python submodule `docutils.nodes` will be extracted and converted to entries in the index.
  - Supported classes are `strong`, `emphasis` and `literal`.
- `sphinx_indexed_defs_skip_indices`: `[]` (_default_) or **list of strings**:
  - All entries that match at least one _regular expression_ within the provided list will not be added to the index (i.e. skipped).
  - An example is `['\bdet\w*','\$i\$-th entry']`, which causes any entry that starts with _det_ to be skipped and the entry _$i$-th entry_ will also be skipped.
  - Note that special characters must be escaped.
- `sphinx_indexed_defs_lowercase_indices`: `true` (_default_) or `false`:
  - If `true`, all extracted entries will be converted to lower case, except for words that are provided in `sphinx_indexed_defs_capital_words` and a prefixed set of common names from beta sciences. 
  - This prefixed set can be found in the source `py`-file of this extension.
  - Users are welcome to add names to this list by forking and opening a pull request. 
  - If `false`, all extracted entries will be added to the index as written.
- `sphinx_indexed_defs_index_titles`: `true` (_default_) or `false`:
  - If `true`, any title provided in a `prf:definition` admonition will also be added as an entry to the index.
  - If `false`, all titles in `prf:definition` admonitions will be ignored.
- `sphinx_indexed_defs_capital_words`: `[]` (_default_) or **list of strings**:
  - See `sphinx_indexed_defs_lowercase_indices`.
- `sphinx_indexed_defs_remove_brackets`: `true` (_default_) or `false`:
  - If `true`, any extracted term containing words between matching opening and closing round brackets, i.e. `(` and `)`, are converted to two entries: one with the entire term with all round brackets removed, and one with all words between matching round brackets removed (including the brackets).
  - An example: the extracted term `(id) dignissim` will result in two entries: `id dignissim` and `dignissim`.
  - If `false`, no parsing of terms with brackets will occur and terms are converted to entries as written.
- `sphinx_indexed_defs_force_main`: `true` (_default_) or `false`:
  - If `true`, all extracted terms will be added as the **main** entry to the index, which means the entry will be emphasized in the generated index.
  - If `false`, extracted terms will not be emphasized in the generated index.
- `sphinx_indexed_defs_index_theorems`: `true` (_default_) or `false`:
  - If `true`, any title provided in a `prf:theorem`, `prf:lemma`, `prf:conjecture`, `prf:corollary` or `prf:proposition` admonition will also be added as an entry to the index.
  - If `false`, all titles provided in `prf:theorem`, `prf:lemma`, `prf:conjecture`, `prf:corollary` and `prf:proposition` admonitions will be ignored.
 
## Provided code

In case a single admonition should be skipped during indexing, add the class `skipindexing` to the admonition, for example:

```md
:::{prf:definition} Lorem
:class: skipindexing

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse **Pharetra**, ex ut commodo varius,
est justo vestibulum nunc, *(id) dignissim* lorem nibh in mauris. Duis varius lorem et neque posuere,
ac elementum eros consequat. Maecenas sed risus suscipit, **fermentum Kelvin** quam vitae, consectetur
augue. Maecenas aliquam leo vitae velit interdum efficitur.
:::
```

## Example

An example of an index generated using this extension can be found at https://douden.github.io/openlabook/main/genindex.html.

## Contribute

This tool's repository is stored on [GitHub](https://github.com/TeachBooks/Sphinx-Indexed-Definitions). 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-Indexed-Definitions). 
The `README.md` of the branch `manual` is also part of the [TeachBooks manual](https://teachbooks.io/manual).
