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鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Feature: Add Documenation Linting to CI/CD #178

Open
2 tasks done
nickytonline opened this issue Sep 27, 2023 · 17 comments
Open
2 tasks done

Feature: Add Documenation Linting to CI/CD #178

nickytonline opened this issue Sep 27, 2023 · 17 comments
Assignees
@ebanner
Labels
accepting prs Please work on this 馃挕 feature A label to note if work is a feature

Comments

@nickytonline
Copy link
Member

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

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

Contributing Docs

  • I agree to follow this project's Contribution Docs
@nickytonline nickytonline added 馃挕 feature A label to note if work is a feature 馃憖 needs triage labels Sep 27, 2023
@nickytonline nickytonline changed the title Feature: Add Liniting to CI/CD Feature: Add Documenation Liniting to CI/CD Sep 27, 2023
@nickytonline nickytonline changed the title Feature: Add Documenation Liniting to CI/CD Feature: Add Documenation Linting to CI/CD Sep 27, 2023
@CBID2
Copy link
Contributor

CBID2 commented Oct 2, 2023 •
edited

That would be helpful @nickytonline! :)

@CBID2 CBID2 added accepting prs Please work on this and removed 馃憖 needs triage labels Oct 2, 2023
@CBID2 CBID2 assigned CBID2 and nickytonline and unassigned CBID2 Oct 3, 2023
@nickytonline
Copy link
Member Author

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
Copy link
Contributor

CBID2 commented Oct 3, 2023

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

@CBID2 CBID2 assigned CBID2 and unassigned nickytonline Oct 17, 2023
@CBID2 CBID2 mentioned this issue Oct 23, 2023
Closed
19 tasks
@nickytonline
Copy link
Member Author

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
Copy link
Contributor

CBID2 commented Jan 18, 2024

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.

@CBID2 CBID2 self-assigned this Jan 30, 2024
@ebanner
Copy link

ebanner commented Apr 3, 2024

.take

@github-actions GitHub Actions
Copy link

github-actions bot commented Apr 3, 2024

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

@CBID2
Copy link
Contributor

CBID2 commented Apr 3, 2024

.take

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

@github-actions GitHub Actions
Copy link

github-actions bot commented Apr 3, 2024

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
Copy link

ebanner commented Apr 3, 2024 •
edited

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
Copy link
Contributor

CBID2 commented Apr 3, 2024

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
Copy link

ebanner commented Apr 3, 2024 •
edited

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
Copy link
Contributor

CBID2 commented Apr 3, 2024

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
Copy link

ebanner commented Apr 3, 2024

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

@ebanner
Copy link

ebanner commented Apr 3, 2024 •
edited

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
Copy link
Member

BekahHW commented Apr 3, 2024

@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
Copy link
Contributor

CBID2 commented Apr 4, 2024

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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@ebanner ebanner

Labels
accepting prs Please work on this 馃挕 feature A label to note if work is a feature
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

feat: Adding vale linter CBID2/opensauced-docs
4 participants
@nickytonline @ebanner @BekahHW @CBID2