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?

Hobbledehoy

I don't understand what you are trying to do. A glossary is a collection of terms and their explanations. You are not using the glossary directive as it is described at sphinx-doc.org/markup/para.html#directive-glossary. – Clevie

@mzjn: Question edited! – Hobbledehoy

There seems to be some misunderstanding here. Sphinx will not automatically populate a back-of-the-book glossary based on multiple glossary directives sprinkled throughout the document. That is not how it works. If you want a single glossary at the end of your document, include one glossary directive in which you add all terms and definitions (by hand). – Clevie

@mzjn: But if I spread single ..glossary:: commands over the whole documentation, sphinx is integrating links to the sites, where the command is placed. I lose this nice automatization if I concentrate alle glossary terms in one single command?! Or am I wrong? oO Also a glossary command will be printed out in your document, so what to do with these single line command? And in the official documentation they say I have to place these commands right in top of the headlines to link correctly! oO The glossary command will be printed out in a LaTeX PDF, so what to do with this single command line – Hobbledehoy

A glossary contains terms and definitions. But in your examples in the question, there are no terms or definitions. Where are they? I am sorry, but I still don't understand what you want to achieve. – Clevie

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.

Clevie

Then I will use the ..index:: command from now on. Then the only thing I dont understand is: How can I make the cross-linking (auto links) work, if I dont strew the index command over the whole documentation. (If I have all in a single line?) You told me that it is possible! So what is the clue? – Hobbledehoy

Don't you get an alphabetical index with page numbers in the PDF? Or is the problem something else? – Clevie

It is linking, but to the position where I placed the command, so what is the clue of getting all .. index:: items I want in 1 single command line ? With this command style I'll have to place it in every single headline within my documentation! Or isn't there a possability to get all items in 1 command? And btw, thanks for all your patience XD. – Hobbledehoy

Suggestion: create a new question with a small but complete example that shows exactly what you do, and explain what it is that doesn't work. I don' think we can solve this by discussing in comments. – Clevie

(I am looking for some kind of cross linking, like the way you use it for figure or image numbers (example: :num:figure #figure-reference) to have all of my index items at 1 point into my documentation. I dont want to scatter 100 commands over different places into my document.) – Hobbledehoy

Alright, I will open a new question...please close this threat. – Hobbledehoy

Answer 2

use http://sphinx-doc.org/markup/misc.html#directive-index to create an index at the end of your book

Destructor

It doesn't matter if I use the .. index:: command or the .. glossary:: command, because both destroy my headlines. Same syntax, same problem. I am searching for a way to make a box or stuff (like some kind of a div box) arround the headline and it's underline to make it work with my commands. – Hobbledehoy

Or a seperat command line which wont be seen in the print output. – Hobbledehoy