glossarpy 0.0.7

Create RST and plaintext glossaries easily

glossarpy

Generate plaintext or reStructuredText (RST) glossaries/dictionaries for documentation with Python. When output is set to RST, glossarpy will automatically give each entry an internal link, allowing for easy cross-referencing within and outside the glossary it generates. Links to external URLs are also supported.

Usage

pip install glossarpy

Once glossarpy is installed in your Python environment, you can import it like any other module. See examples/ for some typical use cases.

glossarpy contains three classes:

• GlossEntry - A single glossary entry which at a minimum contains a name for the entry. It may optionally include a definition, a pronunciation guide, a link to another entry, a link to an external website, or a note about how a term is specific to a certain context.
• GreatGloss - A group of GlossEntry objects. A GlossEntry does not need to be inside a GreatGloss, but a GreatGloss needs at least one GlossEntry in it (in its self.glosslist to be specific) to actually be useful. Use the add_entry() function to add a single GlossEntry to a GreatGloss, or add_entries() to add a list of GlossEntry objects to a GreatGloss.
• GlossTxt - Common functions to handle text output for GlossEntry and GreatGloss. Not really useful on its own.

GlossEntry's attributes

To declare a GlossEntry, all you need is their name: WDL = GlossEntry("WDL") will create a GlossEntry object with a name field of "WDL".

Here's a full list of fields that a GlossEntry can contain (all are type string except updated which is type datetime from the datetime module): * name - entry's name; spaces are supported, do not use [brackets] * acronym_full - if acronym, what is the full name. if blank, assumed to not be an acronym. * further_reading - URL to a webpage, usually an "official" one associated with the term * institute - which institution or context is the phrase associated with? * pronunciation - pronunciation (ex: wdl - "widdle") * seealso - links to another GlossEntry * updated - when the entry was last updated

Linking one GlossEntry to another GlossEntry

The definition and acronym_full arguments can reference other GlossEntry objects by their name field. To do so, encapsulate the entry title you which to reference with brackets, such as WDL = GlossEntry("WDL", acronym_full="[Workflow Description Language]") or WDL = GlossEntry("WDL", definition="A shorthand for [Workflow Description Language]"). When outputting to RST, this will create an internal hyperlink to a GlossEntry that has name="Workflow Description Language" assuming such a GlossEntry exists.

Do not put any alphanumeric characters immediately before or after either bracket.

acronym_full will not link to another entry if brackets are not included, e.g. GCP = GlossEntry("GCP", acronym_full="Google Cloud Platform") would not link a GlossEntry seealso can also reference another GlossEntry object by name, but it does not need brackets, because it assumes only links to other entries will be put in there. i.e. GCP = GlossEntry("GCP", seealso="AWS").

Contributors

As noted in https://github.com/aofarrel/glossarpy/issues/2 I'm seeking some guidance on ensuring this repo is packaged correctly. I am relatively new to this side of Python and would appreciate contributions.

To setup a dev environment:

1. Set up a Python venv. Not strictly necessary, but good practice.

python3 -m venv ./venv
source venv/bin/activate

2. Pull this repo
3. pip install -r requirements-dev.txt

Compiling RST output in Sphinx

This repo's makefile includes commands to show you what a glossary made glossarpy looks like inside a readthedocs template of Sphinx, by leveraging Dockstore's documentation repo. If you want to be able to do that, pull the Dockstore documentation repo, and have it on the same level as this repo, i.e.

 .
 ├── dockstore-documentation/
 └── glossarpy/

Then, run make reqs. Once you have run make reqs once, you can run make all or make html to your heart's content (until you leave your venv of course).