[ANN] Glossaries.jl

Package Announcements
1

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

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

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

7 Likes
2

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.

1 Like
3

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 :slight_smile: