feat: add glossary

[ghost]

Signed-off-by: Lalith Vipulananthan lalith.vipulananthan@tier4.jp

Description

In the Autoware documentation, acronyms are used quite often (eg: AWF for Autoware Foundation) but when doing so we always have to consider adding an explanation for an acronym the first time it is used on a particular page. However, this process can lead to duplicate explanations across multiple pages of the documentation. One potential solution to this problem is to create a glossary that can be used as a single source of explanation for acronyms and commonly used terms that may be unknown to new Autoware contributors.

I created a discussion to get feedback on potential solutions, and the initial suggestion was to start with a basic glossary that expands acronyms and look into a more detailed glossary later on.

mkdocs provides an extension that enables tooltips for acronyms or terms that are defined in a separate mkdocs file and then auto-included in every document file. The new abbreviations.md file in this PR contains an initial draft of terms which can be expanded/modified over time as new documentation pages and their associated acronyms are added.

Pre-review checklist for the PR author

The PR author must check the checkboxes below when creating the PR.

• I've confirmed the contribution guidelines.
• The PR follows the pull request guidelines.

In-review checklist for the PR reviewers

The Reviewers must check the checkboxes below before approval.

• The PR follows the pull request guidelines.

Post-review checklist for the PR author

The PR author must check the checkboxes below before merging.

• There are no open discussions or they are tracked via tickets.

After all checkboxes are checked, anyone who has write access can merge the PR.

[kenji-miyake]

@LalithVipulananthan We have to merge #149 first.
https://github.com/autowarefoundation/autoware-documentation/runs/6981371661?check_suite_focus=true#step:3:284

[github-actions]

Documentation URL: https://autowarefoundation.github.io/autoware-documentation/pr-150/
Modified URLs:

• https://autowarefoundation.github.io/autoware-documentation/pr-150/includes/abbreviations/

[kenji-miyake]

It's corrupted and shown on all pages, which I feel a bit noisy.

How about simply placing it as docs/glossary.md?

[kenji-miyake]

Or should I install some additional dependencies to the CI workflow?

[ghost]

Reading the mkdocs documentation for this, the idea was to just add tooltips that would appear when hovering over an acronym that is included in the abbreviations.md file. I did not expect the text of the abbreviations file to be added.

That said, if a change is made to add a new extension to mkdocs, does a change also need to be made to the CI/CD workflow in order for that extension to be added to the live documentation site?

If a change to the CI/CD workflow is not required, then I will see what I find by asking the mkdocs community. If all else fails, we can just make it a generic glossary file as you suggest. However, in that case, I would want to provide a slightly more detailed explanation for each point and so I would need to rethink the format of the file.

[kenji-miyake]

Okay, I'll investigate the usage and fix the issue!

[ghost]

@kenji-miyake I think the autofix commit may be causing the problem here.

In the mkdocs documentation for tooltips, each entry in the abbreviations file should have an asterisk at the start of the line. However the ci(pre-commit): autofix has replaced the asterisks with underscores.

In theory, reverting that change should fix the issue. 🤔

[kenji-miyake]

I see. I'll check it.

[kenji-miyake]

Hmm, if I revert the pre-commit changes, it didn't work in my local machine. 🤔

[kenji-miyake]

@LalithVipulananthan I'm sorry to be late.

You needed the abbr extension.
Also, as you say, _ instead of * didn't work. So I added prettier-ignore.

Now it works!

[kenji-miyake]

pre-commit-optional is fixed in #157.