[ENH] Generate glossary page from schema

[tsalo]

Closes #900.

This is just a first draft. It does not include links from the glossary back to the specification text, or even collect info about where the terms are used in the text.

I've included anchors for each of the object definitions, so it should be fairly easy to link to the appropriate place in the glossary from things like tables in the text.

Changes proposed:

• Create new appendix, Glossary, with all schema objects rendered.
• Replace single underscore used to delineate metadata fields with the same name, but different definitions, with two underscores, to match the convention proposed in [SCHEMA] Add TSV column files #827.
• Add descriptions for a couple of objects where that field was empty.
• Add functions to generate the glossary from the schema.

[tsalo]

Alternatively, I could organize them by type first, instead of including the type after the term, in parentheses. Not sure which would be preferable.

EDIT: Also, in a perfect world, there would be some way to access the relevant place within the associated YAML file, like "source" links in Sphinx-generated documentation.

[Remi-Gau]

Had a quick look and am generally in favor of this, as it might help users in general.

Does that make the entities appendix page rerundant though?

[Remi-Gau]

I could organize them by type first, instead of including the type after the term, in parentheses. Not sure which would be preferable.

A way to dynamically sort / filter them by type or whatever other criterion would be the best but not sure how feasible it is in MkDocs and would have to be nuked for the PDF rendering.

I would start with alphabetical and progressively improve later.

[sappelhoff]

Does that make the entities appendix page rerundant though?

I don't think this makes the "entities" appendix redundant - these are essentially different pieces of information, aren't they?

I would start with alphabetical and progressively improve later.

agreed!

nuked for the PDF rendering.

@tsalo could you please rebase this PR on master (or merge master) so that we can see how the rendered PDF looks like?

Thanks!

[tsalo]

A way to dynamically sort / filter them by type or whatever other criterion would be the best

@Remi-Gau that's definitely in the wishlist, along with links back to sections of the specification that use each term.

I would start with alphabetical and progressively improve later.

Sounds good. I'll keep it as-is then.

@tsalo could you please rebase this PR on master (or merge master) so that we can see how the rendered PDF looks like?

@sappelhoff done!

[Remi-Gau]

Does that make the entities appendix page rerundant though?

I don't think this makes the "entities" appendix redundant - these are essentially different pieces of information, aren't they?

Well let's just say that the entities page is a subset of the glossary. See the example of the hemisphere entity below.

• https://bids-specification--923.org.readthedocs.build/en/923/99-appendices/09-entities.html#hemi

• https://bids-specification--923.org.readthedocs.build/en/923/99-appendices/14-glossary.html#hemisphere-entities

I don' think it is necessarily an issue though.

[tsalo]

Eventually, it would be great to have the glossary replace the Entities appendix. Imagine hovering your mouse over a term in the specification and the glossary entry pops up! However, at the moment, I think the glossary is just too big and difficult to navigate for users to rely on it for something as common as checking entity definitions.

EDIT: There are some plugins that should make hover tooltips possible, like md-tooltips, md-tooltips-link, and mkdocs-tooltips.

[tsalo]

@sappelhoff would you rather I wait on @effigies's review or can we merge now that there are two approvals?

[sappelhoff]

Let's merge :-) 🚀 Thanks @tsalo