search

shopware / docs

Shopware 6 developer docs
https://developer.shopware.com/
50 stars 249 forks source link

Automated documentation linting #755

Closed swsrmes closed 9 months ago

swsrmes commented 1 year ago

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 commented 1 year ago

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

Isengo1989 commented 10 months ago

@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 :+1:

Isengo1989 commented 9 months ago

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

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 :blue_heart: