[doc] Add a CI check for the doc being properly generated

[Pierre-Sassoulas]

Type of Changes

	Type
✓	✨ New feature
✓	📜 Docs

Description

Refs #5953

Refs #6735 (comment)

Require #8949, #8950, #8951, #8956

[coveralls]

Pull Request Test Coverage Report for Build 3400448677

• 0 of 0 changed or added relevant lines in 0 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 95.38%

---

Totals
Change from base Build 3400152690:	0.0%
Covered Lines:	17239
Relevant Lines:	18074

---

💛 - Coveralls

[Pierre-Sassoulas]

Task failed successfully. I think we need a better error message because it's very unclear that the issue is that the file were modified during the make. Ideally pre-commit could autofix, but I don't know how well that work with the "manual" option.

[Pierre-Sassoulas]

I think that adding this hook as pre-push is reasonable. The alternative I think would be to add it all the time but only if some specific file are modified like checkers in pylint/checkers and python file in doc/exts/.

Con/pro of the pre-push hook:

• ➖ No automatic fix
• ➖ Need to install pre-commit with command that is not well known imo

• ➕ Not launched for every commit locally

Con/pro of the pre-commithook:

• ➕ Automatic fix online
• ➖ It's very slow, we're going to --no-verify a lot of commits if we don't do something about it

[DanielNoord]

I'm still not sure about adding this as a local pre-commit hook. I worry that I would start using --no-verify quite a bit more. For me creating the documentation takes 30+ seconds while also spinning up all fans my laptop can find 😅 When I'm working on the primer for example this is something I would like to avoid.

On pydocstringformatter I created a workflow that builds the documentation and then checks if there is a diff after that build. If there is we fail the workflow. Would that be okay here as well?

[Pierre-Sassoulas]

@DanielNoord @jacobtylerwalls sorry I changed the contributor doc a little more than strictly necessary but it was in such a state of disrepair that I could not help it.

[Pierre-Sassoulas]

Let it be noted that the tests fail successfully before the generation of the doc on cc2b93a

[github-actions]

🤖 According to the primer, this change has no effect on the checked open source code. 🤖🎉

This comment was generated for commit 98e684b

[Pierre-Sassoulas]

I chose to hard code the value in a dict, the generic way to do it was not worth it as we have so little dynamically generated values.

[Pierre-Sassoulas]

Sorry for the ping on this one, I'm going to create 2 new merge requests to not mix things up (#8949 and #8950).

[github-actions]

🤖 According to the primer, this change has no effect on the checked open source code. 🤖🎉

This comment was generated for commit ea000d9

[github-actions]

🤖 According to the primer, this change has no effect on the checked open source code. 🤖🎉

This comment was generated for commit 8edc45c

[github-actions]

🤖 According to the primer, this change has no effect on the checked open source code. 🤖🎉

This comment was generated for commit c08cfc4

[Pierre-Sassoulas]

I'm thinking that it could be nice to launch the fast python generation directly in a pre-commit hook but I want to prioritize the conf upgrade tool atm