Broken link in docs

[Strooom]

When navigation to the rules documentation (https://github.com/arduino/arduino-lint/blob/main/docs/rules.md), clicking on libraries, it leads to https://github.com/arduino/arduino-lint/blob/main/docs/rules/library.md but this gave an Error 404 on github

[per1234]

Hi @Strooom. Thanks for your interest in the Arduino Lint rule documentation.

The reason this link is broken is because this library.md file is programmatically generated from the Arduino Lint code.

This content is intended to be read on the documentation website here:
https://arduino.github.io/arduino-lint/dev/rules/

I considered the idea of storing the generated documentation in the repository alongside the code when I started working with the system in the Arduino CLI repository, but I was unsure if it would be worth the effort because the documentation will need to be updated on every code change that affects it. Since that time, we added a documentation versioning system and never had any reports until now of people hitting those broken links, even though Arduino CLI is a very popular project. That made me feel like it was not so much needed.

But perhaps there is a way to more effectively communicate that the files under docs are only the source code of the website content. MkDocs expects that all the Markdown files under docs are meant to be part of the website, so adding a README.md to the folder to contain the explanation would cause the website validation to fail. But a README.txt could be used instead to avoid that problem.