Feature: Add Documenation Linting to CI/CD

[nickytonline]

Type of feature

📦 Chore

Current behavior

Currently there is nothing checking for stuff like an acronym being used before it's defined in documentation.

I came across this while reviewing #177

Suggested solution

It made me think of the docs linting we used at Netlify. I think this could be a great addition to maintaining our docs. More about it here, https://www.netlify.com/blog/a-key-to-high-quality-documentation-docs-linting-in-ci-cd/

Additional context

No response

Code of Conduct

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

Contributing Docs

• [X] I agree to follow this project's Contribution Docs

[CBID2]

That would be helpful @nickytonline! :)

[nickytonline]

I can definitely implement this, but if someone else wants to take it on, go for it. If not, I'll get around to this during Hacktoberfest at some point.

[CBID2]

I wanted to do it for Hacktoberfest but was not sure what to put @nickytonline.

[nickytonline]

Unassigning you for the moment @CBID2 as the PR has been open since October 2023. If you decide to pick this up again, feel free to assign yourself.

[CBID2]

Unassigning you for the moment @CBID2 as the PR has been open since October 2023. If you decide to pick this up again, feel free to assign yourself.

Hey @nickytonline. I still have to figure out a way to configure the action.

[ebanner]

.take

[github-actions[bot]]

Thanks for taking this on! If you have not already, join the conversation in our Discord

[CBID2]

.take

Good luck @ebanner! :) Take a look at my test repo here to see what I tried to do.

[github-actions[bot]]

Thanks for being interested in this issue. It looks like this ticket is already assigned to a contributor. Please communicate with the assigned contributor to confirm the status of the issue.

[ebanner]

Cool @CBID2, thanks!

I'm looking specifically to see if I can get vale to check for undefined abbreviations. In your research, did you see if that is possible?

[CBID2]

Cool @CBID2, thanks!

I'm looking specifically to see if I can get vale to check for undefined abbreviations. In your research, did you see if that is possible?

Not quite @ebanner. The issue I had was the linter working on files that were not being pushed to a PR.

[ebanner]

I found a plugin to textlint that seems to do what we want

https://github.com/textlint-rule/textlint-rule-unexpanded-acronym

It also occurs to me since our use case is narrow, we could just roll our own custom script if the overhead of a linter is too big

[CBID2]

I found a plugin to textlint that seems to do what we want

https://github.com/textlint-rule/textlint-rule-unexpanded-acronym

It also occurs to me since our use case is narrow, we could just roll our own custom script if the overhead of a linter is too big

Looks pretty possible to me @ebanner! :) How can we go about the creating the custom script?

[ebanner]

Ha the custom script route would just be writing like a python script 🙃

[ebanner]

Ok so I ran textlint-rule-unexpanded-acronym on docs/

edward@Edwards-MacBook-Air open-sauced-docs % npx textlint --rule unexpanded-acronym docs     
npm info using [email protected]
npm info using [email protected]

/Users/edward/Code/open-sauced-docs/docs/community/100-days-of-oss.md
  1:1  error  "OSS" is unexpanded acronym. What does "OSS" stand for?  unexpanded-acronym

/Users/edward/Code/open-sauced-docs/docs/contributing/introduction-to-contributing.md
  1:1  error  "CSS" is unexpanded acronym. What does "CSS" stand for?  unexpanded-acronym

/Users/edward/Code/open-sauced-docs/docs/contributing/opensauced-maintainers-guide/community-maintainers-guide.md
  1:1  error  "GIF" is unexpanded acronym. What does "GIF" stand for?  unexpanded-acronym

/Users/edward/Code/open-sauced-docs/docs/contributing/set-up-authentication.md
  1:1  error  "API" is unexpanded acronym. What does "API" stand for?  unexpanded-acronym

/Users/edward/Code/open-sauced-docs/docs/contributing/technical/resolve-merge-conflicts.md
  1:1  error  "NOTE" is unexpanded acronym. What does "NOTE" stand for?  unexpanded-acronym

/Users/edward/Code/open-sauced-docs/docs/contributing/technical/setup-repo-with-git.md
  1:1  error  "CLI" is unexpanded acronym. What does "CLI" stand for?  unexpanded-acronym

/Users/edward/Code/open-sauced-docs/docs/contributing/triage-guide.md
  1:1  error  "CSS" is unexpanded acronym. What does "CSS" stand for?  unexpanded-acronym

/Users/edward/Code/open-sauced-docs/docs/contributors/contributors-guide.md
  1:1  error  "URL" is unexpanded acronym. What does "URL" stand for?  unexpanded-acronym
  1:1  error  "API" is unexpanded acronym. What does "API" stand for?  unexpanded-acronym

/Users/edward/Code/open-sauced-docs/docs/features/contributor-insights.md
  1:1  error  "PRO" is unexpanded acronym. What does "PRO" stand for?  unexpanded-acronym

/Users/edward/Code/open-sauced-docs/docs/features/highlights.md
  1:1  error  "URL" is unexpanded acronym. What does "URL" stand for?  unexpanded-acronym

/Users/edward/Code/open-sauced-docs/docs/features/repo-insights.md
  1:1  error  "URL" is unexpanded acronym. What does "URL" stand for?  unexpanded-acronym
  1:1  error  "PRO" is unexpanded acronym. What does "PRO" stand for?  unexpanded-acronym

/Users/edward/Code/open-sauced-docs/docs/features/workspaces.md
  1:1  error  "PRO" is unexpanded acronym. What does "PRO" stand for?  unexpanded-acronym
  1:1  error  "URL" is unexpanded acronym. What does "URL" stand for?  unexpanded-acronym

/Users/edward/Code/open-sauced-docs/docs/maintainers/maintainers-guide.md
  1:1  error  "VIP" is unexpanded acronym. What does "VIP" stand for?  unexpanded-acronym
  1:1  error  "URL" is unexpanded acronym. What does "URL" stand for?  unexpanded-acronym

/Users/edward/Code/open-sauced-docs/docs/opensauced-guides/job-seekers-guide/categorize-contributions.md
  1:1  error  "URL" is unexpanded acronym. What does "URL" stand for?  unexpanded-acronym
  1:1  error  "CSS" is unexpanded acronym. What does "CSS" stand for?  unexpanded-acronym

/Users/edward/Code/open-sauced-docs/docs/opensauced-guides/students-guide/students-guide.md
  1:1  error  "URL" is unexpanded acronym. What does "URL" stand for?  unexpanded-acronym
  1:1  error  "API" is unexpanded acronym. What does "API" stand for?  unexpanded-acronym
  1:1  error  "OSS" is unexpanded acronym. What does "OSS" stand for?  unexpanded-acronym

/Users/edward/Code/open-sauced-docs/docs/opensauced-packages/check-engines.md
  1:1  error  "API" is unexpanded acronym. What does "API" stand for?  unexpanded-acronym

/Users/edward/Code/open-sauced-docs/docs/opensauced-packages/semantic-release.md
  1:1  error  "URL" is unexpanded acronym. What does "URL" stand for?  unexpanded-acronym

/Users/edward/Code/open-sauced-docs/docs/tools/pizza-cli.md
  1:1  error  "CLI" is unexpanded acronym. What does "CLI" stand for?  unexpanded-acronym

@BekahHW @nickytonline how useful does this output look? What do you guys think?

[BekahHW]

@ebanner it looks like it's grabbing all the caps words, which means it's grabbing some words that are caps for emphasis.

PR would fall under there and that would be great, but I'm not sure about it grabbing all the words.

[CBID2]

With that in mind, I think it would help if the linter focused on PRs that had incorrect Markdown syntax. What do you think @BekahHW?