Glossary for Taqueria Documentation

[hu3man]

Describe the feature you would like

A glossary of terms used in Taqueria that supports hover-over definitions for users

Is this feature solving a problem?

Details about the problem your feature solves

Please share any additional details you have?

One framework: https://essif-lab.pages.grnet.gr/framework/docs/terminology-plugin-instructions#generate-the-glossary-page

Tasks

• [x] Implement framework to handle glossary #490
• [x] Update CD/CD Pipeline to support the parse and glossary yarn commands before CF build #490
• [ ] Extract list of terms to define from site
• [ ] Build glossary pages for terms

Code of Conduct

• [X] I agree to follow this project's Code of Conduct

[russellmorton]

@hu3man, related issue has a link to preliminary work done.

[hu3man]

Blocked

There are several implementations of this functionality:

• https://githubmemory.com/repo/essif-lab/framework
• https://github.com/woondossier/docusaurus-terminology
• https://www.npmjs.com/package/@digigov/docusaurus-terminology

Unfortunately, they all share two common libraries:

• @docusaurus-terminology/parser
• @docusaurus-terminology/term

The parser is available for both NPM and Yarn, but the term library is only available through Yarn

We currently use npm to manage Docusaurus, this prevents the usage of the term library which provides the text replacement and tooltip functionality

The options I can see moving forward are:

1. Refactor Docusaurus and the Website to use Yarn rather than NPM (Docusaurus has first-class support for both)
2. Use both NPM and Yarn together (generally an anti-pattern)

[russellmorton]

@hu3man let's split this ticket into:

• Glossary
• Hover over definitions

so that we can get the glossary on the site.

[hu3man]

The way this works is that each definition gets it's own *.mdx file that exists in a hidden directory that is then rendered and both libraries are required for this

[hu3man]

@alexzbusko @GImbrailo @jevonearth , what are your thoughts on parallel pkg managers vs refactoring from NPM to yarn?

From my understanding, either approach is going to affect our CI/CD pipeline and involves trade-offs between upfront effort and maintenance and stability

[hu3man]

Currently refactoring to Yarn in PR #478

[hu3man]

Where abouts in Notion is the preliminary glossary @russellmorton ?

[hu3man]

Deprioritizing due to more important in-scope work for milestone (scaffold and state API docs)