Figuring out how to upgrade rstcheck to 6 for docs builds

Project Discussions
1

TL;DR; - we’ve pinned rstcheck in the community and core package builds to < 6 because it triggers failures due to Update docs build requirements · Issue #78478 · ansible/ansible · GitHub.

Based on that info, it looks like what was failing was caused by our use of reusable snippets. Since the underling rstcheck bug isn’t fixed afaik, maybe it’s time we reconsider reusable snippets so we CAN actually modernize rstcheck?

Looks to be less than 20 reused snippets in the docs repo. Of course how many places they would need to be updated is a different story. And a cursory read of the problem suggests not all snippets have to go, but any that use sphinx directives would have to be replaced somehow.

So before opening an issue to do this, what do folks think? Is it worth troubleshooting this once again to see if there is a way we can get away from this pinning to and old version of rstcheck even if it means stopping reusable snippets of docs?

2 Likes
2

DaWGs meeting consensus was yes, since we don’t have heavy use of snippets, let’s try out rstcheck 6 and see if we can replace the problematic snippets.

Note: check out the rstcheck migration guide for what other changes might be necessary.

3 Likes