[ANN] Glossaries.jl

kellertuer · January 11, 2026, 1:37pm

When you are writing documentation for a package, it might happen that you are repeating yourself

when a certain parameter appears in several functions
when a certain field appears in several structs
when keywords are available in several functions
when you have certain, e.g., mathematical terms that you want to resuse

With these these, we identified two challenges

keeping these unified, for example when you fix a typo (I do a lot of typos), you have to remember to fix them everywhere
keeping a consistent format

Starting from ideas when writing the docs from Manopt.jl, we quite often have a Manifold and a cost function to mention as input parameters.

For that we introduce Glossaries.jl!

The package allows to

define a glossary (or sub glossaries) to store for example variables, mathematical terms, or any other terms you would like to store.
use formatters to print the entries. This way, a glossary of variables can be used to print input arguments, keyword arguments or even fields, if the names are similar there as well.
define a glossary of a package, for example Manopt.current_glossary() that allows other packages to access a Glossary of a package as well.

Example

In Manopt.jl the doc string for gradient descent has 4 parameters, manifold, cost, gradient and start point. These appear in a lot of other solvers as well, so they are stored in the Glossary.

These are now interpolated into the doc string as

github.com/JuliaManifolds/Manopt.jl

src/solvers/gradient_descent.jl

cbc66ad3c


      
          # Input
          
          $(_args([:M, :f, :grad_f, :p]))

where _args is a formatter (or “output generator”) from the Glossary to print arguments, see Reference · Glossaries.jl . This yields that all entries mentioned (=input variables here) are printed as

- `name::type`: description

and the manifold :M is for example defined as

github.com/JuliaManifolds/Manopt.jl

src/documentation_glossary.jl

cbc66ad3c


      
          Glossaries.define!(_glossary_variables, :M)
          Glossaries.define!(
              _glossary_variables, :M, :description,
              (; M = "M") -> "a Riemannian manifold ``$(_tex(:Cal, M))``"
          )
          Glossaries.define!(_glossary_variables, :M, :type, "`$(_link(:AbstractManifold))` ")

A tutorial can be found at Get started with Glossaries.jl · Glossaries.jl.

tecosaur · January 11, 2026, 3:10pm

Neat! There’s a package I wrote a while ago for Emacs/Org that might be of interest to you, solving the same problem in a different context.

In particular, I expect you might be interested in the syntax and behaviour described in https://code.tecosaur.net/tec/org-glossary/src/branch/master/org-glossary.org.

kellertuer · January 11, 2026, 7:30pm

Interesting relation; I never got around using emacs, when I see people using it, it seems a bit magic to me (similar to people using vim), but yes, interesting to know for others then

tecosaur · January 12, 2026, 3:15am

It’s scope creep, but I will admit to hoping it would be to you too

More specifically, I think you could have it so that glossaries are defined from markdown, and integrate with Documenter.jl to produce similar result as my package.

kellertuer · January 12, 2026, 7:33am

Yes, one extension could be to load the Glossary from Markdown or YAML. The main reason this is not done for now and also not planned, is, that Glossaries.jl allows for parametrised entries.

For example

github.com/JuliaManifolds/Manopt.jl

src/documentation_glossary.jl

cbc66ad3c


      
          Glossaries.define!(_glossary_variables, :subgrad_f, :name, "∂f")
          Glossaries.define!(
              _glossary_variables, :subgrad_f, :description,
              (; M = "M", p = "p", f = "f", kwargs...) -> """
              the subgradient ``∂$f: $(_math(:Manifold; M = M)) → $(_math(:TangentBundle; M = M))`` of ``$f`` as a function `(M, p) -> X` or a function `(M, X, p) -> X` computing `X` in-place. This function should always only return one element from the subgradient.
              """,
          )

is the definition of the sub gradient (one deterministic element of the subdifferential), so related to :grad_f entry from above. f is always the complete cost function within Manopt, but in some cases arguments might have different names as for the difference-of-convex, where we need (from f = g - h) the subdifferential of a part of the cost and hence have

github.com/JuliaManifolds/Manopt.jl

src/solvers/difference_of_convex_algorithm.jl

cbc66ad3c


      
            p^{(k+1)} ∈ $(_tex(:argmin))_{q ∈ $(_math(:Manifold)))} g(q) - ⟨X^{(k)}, $(_tex(:log))_{p^{(k)}}q⟩
          ```
          
          until the stopping criterion (see the `stopping_criterion` keyword is fulfilled.
          
          # Input
          
          $(_args([:M, :f]))
            total cost function ``f = g - h``
          * `g`: the smooth part ``g`` of the cost function
          $(_args(:subgrad_f; name = "∂h", f = "h"))
          $(_args(:p))
          
          # Keyword arguments
          
          $(_kwargs(:evaluation))
          * `gradient=nothing`:        specify ``$(_tex(:grad)) f``, for debug / analysis or enhancing the `stopping_criterion=`
          * `grad_g=nothing`:          specify the gradient of `g`. If specified, a subsolver is automatically set up.
          $(_kwargs(:stopping_criterion; default = "`[`StopAfterIteration`](@ref)`(200)`$(_sc(:Any))[`StopWhenChangeLess`](@ref)`(1e-8)"))
          * `g=nothing`:               specify the function `g` If specified, a subsolver is automatically set up.
          * `sub_cost=`[`LinearizedDCCost`](@ref)`(g, p, initial_vector)`: a cost to be used within the default `sub_problem`.

where we can reuse the same doc string but modify variable name and the display of f.

Since functions are a bit hard to store in YAML/Markdown, for now I am not sure how to safe those to file.

An integration to Documenter.jl would be neat, I like plugins there a lot. Sadly, I am merely a user of Documenter and have zero knowledge about the magic internals, so there someone else would have to come by and help, as to
where, when, how, … to do such an integration.

tecosaur · January 12, 2026, 7:42am

That all sounds very reasonable. I’m guessing the naming ship may have already sailed, but it seems to me that based on the scope you’ve articulated something like DocstringGlossaries might be a better fit? This could just be me, but when I saw “[ANN] Glossaries.jl” I had no idea what context the package operated in.

kellertuer · January 12, 2026, 7:50am

Yeah that ship has sailed, the package is registered.

We first considered your name, but then felt, since we also make the Glossary (per Module) available to other modules, that the use might even go beyond a usage in doc strings.

edit: We even considered DocumenterGlossaries – but then we really would have needed an integration to Documenter, which is currently not planned (see above, missing knowledge on my side for example).

tecosaur · January 12, 2026, 7:51am

Mmmm. I see. If you expand the capabilities that would be cool indeed, and justify the name I think

GunnarFarneback · January 12, 2026, 7:55am

QED.

Datseris · January 12, 2026, 3:15pm

haha burn Jokes asside, this is really interesting, thanks for sharing!

kellertuer · January 12, 2026, 3:22pm

We do not yet have an extension to discourse, so repetitions in posts of mine might still appear.

Topic		Replies	Views
What are good ways to structure reoccurring phrases in doc-strings General Usage	1	90	August 20, 2024
Documenter.jl: How to avoid repetitions of shared docstrings? General Usage documenter	11	362	May 11, 2025
Best way to document (a reasonable amount of) keywords General Usage	17	898	August 17, 2024
ANN: Announcing DoctorDocstrings.jl Package Announcements package , announcement , documentation	7	975	December 18, 2020
Concise way to apply one docstring to multiple items General Usage documentation	2	101	December 9, 2024

[ANN] Glossaries.jl

Example

Related topics