Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: add glossary #150

Merged
merged 5 commits into from Jun 26, 2022
Merged

feat: add glossary #150

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f26703a
feat: add glossary
Jun 21, 2022
ab2e0d1
ci(pre-commit): autofix
pre-commit-ci[bot] Jun 21, 2022
0281090
ignore *.pyc
Jun 26, 2022
15449f5
add abbr
Jun 26, 2022
d2761e2
add prettier ignore
Jun 26, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
# JetBrains IDEs
/.idea/

# Python
*.pyc

# Vim
*.swp
*.swo
Expand Down
17 changes: 17 additions & 0 deletions includes/abbreviations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
<!-- prettier-ignore -->
*[AVP]: Autonomous Valet Parking
*[AWF]: Autoware Foundation
*[DBW]: Drive-By-Wire
*[ECU]: Electronic Control Unit
*[FMS]: Fleet Management System
*[GNSS]: Global Navigation Satellite System
*[GPU]: Graphics Processing Unit
*[HMI]: Human Machine Interface
*[IMU]: Inertial Measurement Unit
*[MMS]: Mobile Mapping System
*[ODD]: Operational Design Domain
*[OTA]: Over The Air
*[PCD]: Point Cloud Data
*[ROS]: Robot Operating System
*[SLAM]: Simultaneous Localization And Mapping
*[URDF]: Universal Robotic Description Format
4 changes: 4 additions & 0 deletions mkdocs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,7 @@ plugins:
- search

markdown_extensions:
- abbr
- admonition
- attr_list
- codehilite:
Expand All @@ -71,6 +72,9 @@ markdown_extensions:
format: svg
- pymdownx.arithmatex
- pymdownx.highlight
- pymdownx.snippets:
auto_append:
- includes/abbreviations.md
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

@ghost ghost Jun 21, 2022 •
edited by ghost
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

@ghost ghost Jun 22, 2022 •
edited by ghost
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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. 🤔

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see. I'll check it.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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!
image

- pymdownx.superfences:
custom_fences:
- name: mermaid
Expand Down