Glossary Enhancement: Filter Glossary/Glossaries

[GadgetSteve]

Subject: Glossary likely to contain redundant terms or needs to be specific for every project.

Problem

• At the moment every defined term in the glossary is included whether there is a matching :term: or not - this means that every project needs to have a unique glossary, or to reference a common glossary without possibly many redundant terms.

Procedure to reproduce the problem

Add to glossary a definition such as:

ZXZXY 
   This is a term that is **never** used in the document!

and make the documents in any format.

Error logs / results

No Errors

• Document contains definition above but no matching :term: entries.

Expected results

I would like the glossary to possibly automatically or via a filter modifier to the :glossary: entry filter on the actual :term: items present in the document being built and only include those terms in the output documents. N.B. may need to recursively check the filtered glossary entries for :term: items not currently included in case of definitions that introduce other terms but possibly this could be done by linking entries that contain terms defined in other entries so if the child is included the parent is automatically.

Ideally I would be able to have a glossary entry in my current project with include directives to the department glossary, (which might have include directives to the company glossary, etc.).

It would also be possible to have a mechanism for using entries from a default glossary into a generated glossary based on searching the project for :term: items and make this a pre-build step but I suspect that this would be less clean - this mechanism could be a possible "contrib" item.

Reproducible project / your project

• This should be able to be caused/found in any project - I suspect that many current projects have glossary entries without matching :term: items due to either over enthusiastic defining or terms being removed over the life of the document.

Environment info

• OS: Any
• Python version: 2.7.x, >3.3
• Sphinx version: 1.5.3
• Other tools: N/A

[Blendify]

I would be against automatically remove glossary definitions unless it is hidden behind an option.

[GadgetSteve]

@Blendify - I have no problem with auto-hide glossary terms if not used being option selected.

[tk0miya]

-1: I feel a bit strange because this means Sphinx removes automatically the contents which user marked up. I think it is worthy even if not referenced. If not intended, users may remove the entry from glossary.

In your case, your glossary is shared between multiple project. I think it is not common situation.
I propose to make the feature as a 3rd party's extension.

[GadgetSteve]

@tk0miya I would disagree that this is not a common situation - I am sure that there are many of us who are working for companies where they will have the situation where there are company wide, divisional and departmental acronyms as well as project specific acronyms. Additionally, there are language specific and discipline specific entries to consider. The other use case that I hope that this would assist in is where a previous version of the documentation referenced a given term that was deliberately removed, where it was used, for some reason but the glossary entry was overlooked.

Also, I wish to clarify that I am not talking about removing, (from the source), material that the user has typed just not including in the output material that is not referenced anywhere, i.e. there is no matching :term:. This is intended to ensure that the glossary is relevant, I was looking at a manually created QA document the other day where, due to simple concatenation of glossaries by the author, the glossary was actually 2 pages longer than the content but still missed a number of essential definitions of items that were used in that document.

Possibly a more sophisticated mechanism would be to, possibly depending on a setting, include all of the local, manually added project glossary entries in the output but allow :term: resolution from a nested set of default glossary entries, possibly with entries produced this way having an optional source marker i.e. Locally defined :terms: defined in the glossary.rst would simply appear but those auto-resolved from departmental, company wide or industry standard definitions would be marked, possibly with a footnote, denoting which of those sources had been used.

I have no issues with creation of this sort of facility as a 3rd party extension and may make a start on it if there is nothing in the road map that is likely to supersede it.

[Paebbels]

Is there a warning reported if a glossary entry was never referenced? That would be a first start for users to find abandoned entries. Likewise, is there a warning if a term references a non existing entry?

[Blendify]

Is there a warning reported if a glossary entry was never referenced?

No

Likewise, is there a warning if a term references a non existing entry?

Yes

However, for some projects, like one of my own, we do this on purpose to give the reader a broad knowledge of concepts from our documentation.

[Paebbels]

I think Sphinx should emit a warning on unused resources like glossary entries. Moreover, a warning control to disable certain warnings is also missing.

@Blendify can you name or send me the name of your Documentation if it's online? I'm writing a huge documentation on my own which is now grown to 270 rst files and generates circa 800 PDF pages on ReadTheDocs. I would like to see how others organization such big documentations. I was also thinking of providing a glossary. My documentation is called PoC- Library. You'll find my contacts in the authors list matching this user name.

[sebhub]

An option to include only referenced items in the glossary would be great. I want to migrate from a pure Latex documentation to Sphinx. For Latex I use the acronym package for this. With this I can use a common glossary for multiple documents and only include the relevant stuff in the individual documents.

[sebhub]

It would be quite helpful for me, if someone has hints how this could be implemented in Sphinx. I try to work on this.

[tk0miya]

Sorry for not responded. I can agree with emitting a warning for not referenced glossary entry. But I'm not interested in filtering the entries.

[sebhub]

Would it be possible to optionally filter out the not referenced glossary entries once the warning is implemented?

We have a project wide glossary which is included in several documents. The main content of some documents is smaller than the glossary section. This is not really nice. We still need access to the project wide glossary for some terms.

[GadgetSteve]

@sebhub Personally I quite like the idea of being able to cascade glossary resources where you have terms that are specific to this document, to the project, organisation, etc. and the "nearest" is included in your glossary if the term is used in your document.

[brechtm]

Sorry for the noise, but I'm also looking for this functionality. I was wondering whether any of you have found or written a Sphinx extension in the meantime that offers this? @GadgetSteve @sebhub @Paebbels

[christianschmizz]

Any updates on this? I stumbled upon the same problem. It would be nice to have something similar to :local: but for glossary terms.

.. contents:: Table of Contents
    :local:

[partofthething]

Hey folks. I put together a new extension that has a reasonable start on this capability. It will limit the terms shown to those referred to via :term: in the project.

However, it does not yet recurse, so any and all :terms: referred to from within the .. glossary:: directive will always show regardless of whether or not you referred to the base term. Therefore, I recommend using this with glossaries that don't yet point to other terms by link in the definitions.

https://github.com/partofthething/glossaryused