ipypublish.sphinx.gls

ipypublish.sphinx.gls is adapted from sphinxcontrib-bibtex, to provide a sphinx extension that closely replicates the functionality of the LaTeX glossaries package, for referencing glossaries terms, acronyms and symbols provided in a separate file.

This extension loads:

• The bibglossary directive, for setting a file containing terms (see ipypublish.sphinx.gls.directives)

• gls, glsc, glspl, glscpl roles, for referencing the terms (see ipypublish.sphinx.gls.roles)

See also

RMarkdown References, for an example of using this extension within the conversion of a Jupyter Notebook.

Installation

Install ipypublish:

conda install "ipypublish>=0.10"

or

pip install "ipypublish[sphinx]>=0.10"

The key addition to the sphinx configuration file (conf.py) is:

extensions = [
    'ipypublish.sphinx.gls'
]

Also sphinx.ext.mathjax is recommended for rendering math.

The Glossary File Formats

The glossary file can be in one of two formats; a .bib file (recommended) or a .tex file.

The .bib file is a standard BibTeX file (which is initially parsed by bibtexparser), and should contain the following custom entry types:

glossary term (name and description are required fields):

@glsterm{gtkey1,
    name = {name},
    description = {full description \textbf{with latex}},
    plural = {some names},
    text = {alternative text},
    sort = {a},
    symbol = {\ensuremath{n}}
}

acronym (abbreviation and longname are required fields):

@glsacronym{akey1,
    abbreviation = {MA},
    longname = {My Abbreviation},
    description = {full description},
    plural = {MAs},
    longplural = {Some Abbreviations}
}

symbol (name and description are required fields):

@glssymbol{symbol1,
    name = {\ensuremath{\pi}},
    description = {full description},
    plural = {\ensuremath{\pi}s},
    text = {alternative text},
    sort = {sortkey}
}

Alternatively, the glossary can be supplied as a TeX file:

\newglossaryentry{gtkey1}{
    name={name},
    description={full description \textbf{with latex}}
    plural={names},
    text={alternative text},
    sort={a},
    symbol = {\ensuremath{n}}
    }
\newacronym[plural={AAs}]{akey1}{AA}{An Abbreviation}
\newglossaryentry{symbol1}{
    name={\ensuremath{\pi}},
    description={full description},
    plural={\ensuremath{\pi}s},
    text={alternative text},
    sort={b},
    type={symbols}
    }

Note

To parse a glossary in TeX format, the TexSoup package is required.

newglossaryentry with type={symbols} are considered to be symbols, no other types are recognised.

Attention

All labels and description text are converted from latex to rst by Pandoc, then rst to docutils, before being output to the final document.

To skip this conversion (and only output as plain text) set the sphinx configuration variable bibgloss_convert_latex = False

See also

The LaTeX/Glossary guide, for further description of each field.

Usage

:gls:

The gls role will output the ‘name’ or ‘abbreviation’ field of the entry:

:gls:`gtkey1`, :gls:`akey1`, :gls:`symbol1`

name, MA, \(\pi\)

:glspl:

The glspl role will output the ‘plural’ field of the entry, or (if not present) will append an ‘s’ to the ‘name’ or ‘abbreviation’ field.

:glspl:`gtkey1`, :glspl:`akey1`, :glspl:`symbol1`

some names, MAs, \(\pi\)

:glsc:

The glsc and glscpl capitalise the respective labels.

:glsc:`gtkey1`, :glscpl:`gtkey1`

Name, Some names

.. bibglossary:: path/to/glossary

When creating the glossary, it is of note that, if the file extension is not given, then bibglossary will attempt to find the best match in the parent folder. The glossary will be sorted by lower case, ‘name’/’abbreviation’ field, or ‘sort’ field (if it exists).

.. rubric:: Glossary

.. bibglossary:: _static/example_glossary

Glossary

name(1,2,3,4)

full description with latex

\(\pi\)(1,2)

full description

MA(1,2)

My Abbreviation

In order to use multiple glossaries, across one or more files, and avoid hyperlink clashes, it is possible to set a keyprefix to distinguish which glossary is being referenced.

:gls:`a-gtkey1`

.. bibglossary:: _static/example_glossary
   :keyprefix: a-

name

name

full description with latex

Additional options include:

• encoding to specify the encoding of the glossary file

• unsorted to sort the glossary by order of first use (rather than alphanumerically)

• all to output all glossary terms (including unused)

:gls:`b-akey1`

.. bibglossary:: _static/example_glossary
   :encoding: utf8
   :unsorted:
   :keyprefix: b-

MA, Name

MA

My Abbreviation

name

full description with latex

See also

Additional options, known issues, and workarounds can be found in the sphinxcontrib-bibtex, documentation.

Python API

The loading, conversion and storage of each glossary file is handled by a BibGlossDB instance.

from ipypublish.bib2glossary import BibGlossDB
bibdb = BibGlossDB()
bibdb.load("_static/example_glossary")
len(bibdb)

3

This class is a subclass of collections.abc.MutableMapping, and so can be used as a dictionary.

print("gtkey1" in bibdb)
entry = bibdb["gtkey1"]
entry

True
BibGlossEntry(key=gtkey1,label=name)

Entries have attributes for the main fields, and can output to latex.

print(entry.key)
print(entry.label)
print(entry.plural)
print(entry.to_latex())

gtkey1
name
some names
\newglossaryentry{gtkey1}{
    description={full description \textbf{with latex}},
    name={name},
    plural={some names},
    sort={a},
    symbol={\ensuremath{n}},
    text={alternative text}
}