Sphinx Indexed Definitions

Introduction

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

What does it do?

If you code includes an admonition with the source code

:::{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.

If one prf:definition admonition contains a single term several times, it will only be added once to the index. If the same term is used in several admonitions, it will be added to the index with multiple references.

Footnotes in terms will be removed, and the term will be added to the index without the footnote.

Installation

To use this extension, 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 sphinx-indexed-definitions

Step 2: Add to requirements.txt

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

sphinx-indexed-definitions

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.

Configuration

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

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, prf:proposition or prf:notation 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, prf:proposition and prf:notation admonitions will be ignored.
• sphinx_indexed_defs_index_theorems_terms: false (default) or true:
  • If true, any terms provided in a prf:theorem, prf:lemma, prf:conjecture, prf:corollary, prf:proposition or prf:notation admonition will also be added as an entry to the index.
  • If false, all terms provided in prf:theorem, prf:lemma, prf:conjecture, prf:corollary, prf:proposition and prf:notation 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:

:::{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. If you'd like to contribute, you can create a fork and open a pull request on the GitHub repository. The README.md of the branch manual is also part of the TeachBooks manual.