Automated documentation linting

[swsrmes]

Since there are many new, exciting changes happening within the Shopware documentation space, and many concrete processes being established therein, I see a prime opporunity for establishing automated jobs within the documentation PR flow.

An obvious facet is spellchecking, which could be achieved using Github actions such as this. I attempted this previously, but I am currently stuck, with the issue persisting that pyspelling doesn't seem to understand the markdown correctly, despite a markdown extension being added/configured. Given it uses non-vanilla markdown syntax, it could be worth writing some customised regex filters for the extended markdown token set.

There is also a great opportunity to establish documentation linters, which will catch obvious and lexically concrete errors or issues, such as heading casing or flagging date-time format.

In order to achieve such automated enforcing/linting of documentation lexical style rules, we could consider a configurable tools such as TextLint

This could limit the number of mistakes reaching the review stage, and limit load on the reviewers of the docs.

[sushmangupta]

Thank you for the suggestion. We have noted and shall consider incorporating it.

[Isengo1989]

@swsrmes short update - we are currently looking into the options here and compare the given actions with other to use the best option for our docs 👍

[Isengo1989]

@swsrmes we did implement (some PRs pending) the following:

• Spellchecker with own dictionary (.wordlist.txt) - see here
• Languagetool for additional grammar, language and other checks (POC - will be adjusted) - see here
• Filename checks - see here

As for the datetime, we decided to move along without it, since we do have many date formats from different places and code examples. Filtering those out leaves us just with a few, which is not worth the additional effort. Feel free to create a PR on action / workflow that might does that.

The issue will be closed - thank you for the input 💙