How to create a glossary in Sphinx?

Question

I try to make a glossary at the end of my book which contains also the headlines content of my documentation (without description, only a reference to the page). I want to get the headlines into a glossary. But headlines need 2 lines to work, because you have to underline them.

So I am searching a way to combine the .. glossary:: command with a headline OR to make the command invisible under my headlines. I don’t want to see the .. glossary:: command in my LaTeX PDF output, because if I seperat the command I would have my headlines twice. I only want to see the glossary.

But every time I try to, my headlines aren't highlighted anymore and dont work.

They just look like a .. note:: box within the LaTeX PDF and my structures are missing.

How it looks like:

How it should look:

Also the sturctures are missing, so About this Guide isn't anymore a headline.

How it looks:

How it should look:

I searched a lot in the internet and found a lot of descriptions about the .. glossary:: Syntax, but nothing in combination with a headline. So I tried it in many different ways by myself. Here some of the nearby endless examples XD, how I tried it:

1.)

.. glossary:: About this Guide
******************************

2.) ..glossary::

About this Guide
****************

I also indented this part of the code under the .. glossary:: command to get some kind of a block or box, but my headlines weren't highlited anymore and didn't work.

3.)

About this Guide
****************

.. glossary:: About this Guide

In this try, my headline worked fine, but the glossary command was visible within my LaTeX PDF output, so I had it twice.

Is there any way to combine my headlines with a glossary command or to make the seperat glossary command from example 3 invisible?

Answer 1

How to create a glossary in Sphinx?

This is not difficult. Simply add a glossary directive in your document and include all your terms and definitions in it. You could have more than one glossary of course (perhaps for different audiences), but that is basically it. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#glossary-directive.

But the question is more complicated than that. You are trying to do something with the glossary directive that is not supported.

A glossary without terms and definitions is meaningless. I don't see any terms and definitions in your reST examples.

You seem to want some kind of index, generated by markup in the document. And Sphinx can generate a general index, with page numbers, automatically (I suppose you already know this). There is an index directive, and also an index role for defining index entries. But since you insist on using glossaries for this, the question becomes confusing and I am still not completely sure I understand what you want.

By the way, note that terms defined in a glossary show up in the automatically generated index (see Using noindex with glossary in Sphinx).

Moving on, let's assume that you have a section title (heading) that you want to be indexed:

About this Guide
****************

The simplest way to make the text of the heading show up in the generated index is to use an inline index role, like so:

:index:`About this Guide`
*************************

You can also use the block-level index directive:

.. index:: About this Guide

About this Guide
****************

If this answer is not what you are looking for, please clarify the question.