@gotmax23 Hey, in your nox PR you mention enabling ruff checkers [this comment]. I think it might be worthwhile to attempt to capture a more complete view of the tooling and tests somewhere.
I really like the formatters in the noxfile. In fact, after that is merged I think we can reuse much of it for other community docs related repos, like ansible/docsite.
Quite controversially I’d like to enable Ansible Lint runs on sections of the Ansible documentation as part of our ci. I’d like to ask, what other tests and tooling could you envision?
Tangent: does it makes sense to have a discussion tag in a category called discussions? I’ve created feedback-wanted, because that felt useful in other categories - would we use this differently, or are they synonyms?
Yeah, the PR already enables ruff (a Python linter), but it ruff has many optional, more opinionated rules that can be enabled.
I’m not sure if ansible/docsite has any Python code, but if it does, then yeah, the ruff, black, and isort combo is a good choice to maintain consistent code style and avoid common errors.
I’m not sure that Ansible Lint is the best choice for the Ansible community docs. For one thing, I’m not sure if Ansible Lint supports linting embedded playbooks within rst files. Also, it tends to be opinionated and noisy. The playbooks in the docs are meant to show how to use Ansible, not pass every pedantic rule or convention. It would probably be a good idea to set up Ansible Lint in https://github.com/ansible/ansible-examples as per Ansible examples vs. best practices · Issue #266 · ansible/ansible-documentation · GitHub, though.
I know we already use rstcheck in ansible-documentation. @samccann also mentioned https://vale.sh/ on Matrix which seems interesting.
Yeah I should be clear that I don’t think we should do Ansible Lint runs over most of the community docs. I was imagining a future state where we have an additional set of content for cross-project tutorials and how tos. That would probably feature a lot of dev tools and would make a bit more sense to use Ansible Lint there.
Vale is an interesting one and I’ve thought about it before but I have some reservations. Another one that could be useful is codespell, which I think of as sort of vale-light, to catch spelling errors, common grammatical errors, and things like inclusive wording.
So I agree that ansible-lint should be reserved for opinionated docs. By that I mean, docs that aren’t giving the broader “all this is possible in Ansible” approach that most of our existing Ansible documentation uses today. But a new category of cross-project ecosystem docs might benefit from ansible-lint since I think some other projects require it to pass.
Vale vs codespell - I don’t have a strong opinion. Vale I’m mildly familiar with but in general, would be nice to have something that does both a spellcheck/grammar as well as ensures our style guide is implemented per PR so to speak. Not that all the docs would pass today, but anyway. So to me, the tool-of-choice is one we can extend to our needs, but maybe has a base set of requirements available so we’re not recreating the wheel.