Glossary, index, confval and envvar¶

These directives define something a reader can look up, and each has a role that links to it: a glossary term, an index entry, a configuration value, an environment variable. ubCode renders the definitions and resolves the roles in the editor preview and in its html and pdf builds, and publishes the terms and objects in the project’s objects.inv. A role links to a term or object defined on any page of the project, so each specimen below defines what its role links to.

Glossaries¶

The glossary directive is a list of terms and their definitions; the :term: role links to a term from anywhere in the project. A term goes on its own line, with its definition indented below it; several terms on consecutive lines share one definition.

reStructuredText

A glossary

.. glossary::

   Specimen term
   Sample term
      A term defined on this page; both spellings link here.

See the :term:`Specimen term`, also spelled :term:`Sample term`.

Specimen term¶
Sample term¶: A term defined on this page; both spellings link here.

See the Specimen term, also spelled Sample term.

MyST

```{glossary}
MyST specimen term
MyST sample term
   A term defined on this page; both spellings link here.
```

See the {term}`MyST specimen term`, also spelled {term}`MyST sample term`.

The MyST form renders live in the MyST glossary.

The :sorted: option lists the entries alphabetically, whatever order they are written in. A :term: link matches the term without regard to case. A MyST {glossary} is written with the same term-and-indented-definition lines, not with Markdown’s definition-list syntax. How term anchors and classifiers differ from a Sphinx build is in the glossary differences.

Index entries¶

The index directive files entries in the project’s index against the place it is written, and renders nothing visible; the :index: role does the same for a word in the running text, which it shows unchanged. An entry is a type and its parts: single: specimen; entry, pair: specimen; entry (filed under both words), see: and seealso:.

reStructuredText

Index entries

.. index:: pair: specimen; index entry

This paragraph carries the directive's entry,
and the :index:`role <single: specimen; index role>` files one of its own.

This paragraph carries the directive’s entry, and the role files one of its own.

MyST

```{index} pair: specimen; index entry
```

This paragraph carries the directive's entry,
and the {index}`role <single: specimen; index role>` files one of its own.

The MyST form renders live in the MyST index entries.

Note

ubc build pdf cannot place an index directive yet (it reports one as build.pdf_block_unsupported), so the PDF shows this specimen’s source only.

ubCode reads and checks every entry, and makes it findable by the built site’s search, but builds no general index page (see the index-entry differences).

Configuration values¶

The confval directive describes a configuration value, and the :confval: role links to it.

reStructuredText

A configuration value

.. confval:: ex_greeting
   :type: ``str``
   :default: ``"Hello"``

   The word a specimen greets with.

Set :confval:`ex_greeting` to change the greeting.

ex_greeting¶

Type:: str
Default:: "Hello"

The word a specimen greets with.

Set ex_greeting to change the greeting.

MyST

```{confval} ex_myst_greeting
:type: `str`
:default: `"Hello"`

The word a specimen greets with.
```

Set {confval}`ex_myst_greeting` to change the greeting.

The MyST form renders live in the MyST configuration value.

:type: and :default: are shown as a field list above the description, with their inline markup rendered. See the configuration-value differences for where ubCode differs from a Sphinx build.

Environment variables¶

The envvar directive describes an environment variable, and the :envvar: role links to it. Unlike confval, it takes no :type: or :default:.

reStructuredText

An environment variable

.. envvar:: EX_GREETING_HOME

   The directory a specimen reads its greetings from.

Point :envvar:`EX_GREETING_HOME` at another directory to change it.

EX_GREETING_HOME¶: The directory a specimen reads its greetings from.

Point EX_GREETING_HOME at another directory to change it.

MyST

```{envvar} EX_MYST_GREETING_HOME
The directory a specimen reads its greetings from.
```

Point {envvar}`EX_MYST_GREETING_HOME` at another directory to change it.

The MyST form renders live in the MyST environment variable.

See the environment-variable differences for where ubCode differs from a Sphinx build.