Package: glossarpy
glossarpyGenerate plaintext or Sphinx-flavored 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.Usagepip install glossarpyThere are no further requirements for users.Once glossarpy is installed in your Python environment, you can import it like any other module. Seeexamples/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 itsself.glosslistto be specific) to actually be useful. Use theadd_entry()function to add a single GlossEntry to a GreatGloss, oradd_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.How to make a GlossEntryTo declare a GlossEntry, all you need is their name:WDL = GlossEntry("WDL")will create a GlossEntry object with anamefield of"WDL".Here's a full list of fields that a GlossEntry can contain (all are type string exceptupdatedwhich 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 termif an internal link to another documentation page, do not include .html at the endinstitute- which institution or context is the phrase associated with?pronunciation- pronunciation (ex: wdl - "widdle")seealso- links to another GlossEntry by that GlossEntry's name fieldupdated- when the entry was last updatedUseful GlossEntry methodsGenerally, you will want to use GreatGloss methods instead.generate_plaintext() - generate entry as plaintext, see examples/example_print_one_entry.pygenerate_rst() - generate entry as RSTFor either of these methods, you can settimestamp=Trueto have a timestamp get added to the output. That timestamp will be formatted as a comment (ie, will not show up when rendered as HTML in most forms of Sphinx, but will be in the RST file itself) if you are usinggenerate_rst(timestamp=True)Linking one GlossEntry to another GlossEntryThedefinition,acronym_full, andseealsoarguments can reference other GlossEntry objects by theirnamefield. To do so, encapsulate the entry title you which to reference with brackets, such asWDL = GlossEntry("WDL", acronym_full="[Workflow Description Language]")orWDL = GlossEntry("WDL", definition="A shorthand for [Workflow Description Language]"). When outputting to RST, this will create an internal hyperlink to a GlossEntry that hasname="Workflow Description Language"assuming such a GlossEntry exists.Do not put any alphanumeric characters immediately before or after either bracket.Useful GreatGloss methodsadd_entry() - Add a single GlossEntry to GreatGlossadd_entries() - Add a list of GlossEntry objects to GreatGlosssort_entries(ignorecase:bool = True)Sort all GlossEntry objects added by add_entry() or add_entries() alphabetically by their name fieldignorecase: set to True (default) to treat capital and lowercase letters as equivalent (ex:anaconda Anacondas bat zebra), set to False to use default Python sorting (ex:anaconda bat zebra Anacondas)write_glossary(self, outfile:str = "", format:str = "rst", skipTOC:bool = False, skipSource:bool = False, sourcefile:str = None)Write a glossary to the file described in outfile; will raise a RuntimeError if neither this nor GreatGloss' object's outtoc field are definedformat:rstfor RST output,txtfor plaintextcolumns (only matters ifformat=="rst"): Make the TOC render asRST hlist columns. Set to 0 to usecontents with the local flaginstead.skipSource: Whether or not to put a note about the file being autogeneratedsourcefile: If skipSource==True, this is the name of the sourcefile to print.write_toc(self, outtoc:str = "", format:str = "rst", columns:int = 0, skipSource:bool = False, sourcefile:str = None)Write a TOC to the file described in outtoc (will fall back to the GreatGloss' object's outtoc field if one was defined during initalization, or, failing that,toc.rst)All other arguments are equivalent to how they work in write_glossary()Keeping track of source filesThe whole point of glossarpy is to generate files. Generated files should not be updated, instead, their sources should be. To that end, write_toc() and write_glossary() will by default print a notice that they are autogenerated. Ifoutput=="RST"this notice will be a comment that appears only in the RST output, not in HTML files based upon said RST output.If sourcefile is not set (default behavior), the notice will read:DO NOT EDIT THIS FILE. This file is autogenerated from a Python source file, update that instead.You can make this more helpful by settingsourcefileto the name of the file that the entries originate from. In most cases, you can use Python built-in__file__, which will return the name of the Python file that is currently being executed. See examples/example_import_entries.py and examples/example_typical_usage.py for two examples of this, the former of which will result in an output that starts like this:.. DO NOT EDIT THIS FILE. This file is autogenerated from examples/example_import_entries.py, update that instead.There ae some caveats to using__file__, such as the fact this variable is not set when running in an interactive interpreter (resulting in a NameError), so sourcefile is set to None by default. Feel free to replace__file__with a string instead, or not set it at all.If you would like to only print the basename, firstimport osthenos.path.basename(__file__), which in the case of examples/example_import_entries.py would result in:.. DO NOT EDIT THIS FILE. This file is autogenerated from example_import_entries.py, update that instead.ContributorsAs noted inhttps://github.com/aofarrel/glossarpy/issues/2I'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:Set up a Python venv. Not strictly necessary, but good practice.python3 -m venv ./venv
source venv/bin/activatePull this repopip install -r requirements-dev.txtCompiling RST output in SphinxThis 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, pullthe Dockstore documentation repo, and have it on the same level as this repo, i.e..
 ├── dockstore-documentation/
 └── glossarpy/Then, runmake reqs. Once you have runmake reqsonce, you can runmake allormake htmlto your heart's content (until you leave your venv of course).