Automatically give contributors feedback for documentation changes

[neumantm]

I think it would be very helpful to automatically give contributors feedback about documentation changes.

First, it would be nice if the docs of any PR would be build automatically, such that you can see the result.
This would also lower the barrier of entry for new contributors, as they would not need to install all the tools before contributing to the documentation.

Additionally it would be nice to catch any sphinx warnings.
However, this would require all existing sphinx warnings to be fixed first.
(There are currently around 60 warnings.)

Both could be implemented as a GitHub Actions Job.
However, I think it would be more useful to use the service of readthedocs for this.
That ensures the same environment as when the docs are actually build for publishing.

The first step would be to enable readthedocs builds on PRs: https://docs.readthedocs.io/en/stable/pull-requests.html

The second step (after all warnings have been resolved) is to fail on sphinx warnings: https://docs.readthedocs.io/en/stable/tutorial/index.html#making-warnings-more-visible

[neumantm]

I've tested both steps using my own rtd project: running on pr and fail on warnings

I could also look into fixing those warnings if you want to proceed with this.

[psakievich]

@neumantm sure go ahead and put up a PR on this. We do this for the https://github.com/sandialabs/spack-manager project. Sorry we are not super responsive on these sorts of things right now. We're all hands on deck trying to get a multiyear deliverable executed. The core team will have more time for these sorts of things in another month or so.

[neumantm]

Yes of course, no problem.
Ok I'll start working on fixing the existing warning.

However, the first step would be to simply enable the builds on PRs in the readthedocs web UI.
See https://docs.readthedocs.io/en/stable/pull-requests.html
It would be very useful if you (or someone from the team) could enable that.

[jrood-nrel]

https://github.com/sandialabs/spack-manager/blob/fa7cd062d6ce770d2f5d92b210654e1007b33bf5/.github/workflows/docs.yml#L34-L40
This causes the PRs to fail if there are warnings in the documentation. We usually use Github pages for deploying documentation, but we haven't moved Nalu-Wind docs here yet.

[neumantm]

Yes, that is one possibility. However that can also easily be achieved with readthedocs (https://docs.readthedocs.io/en/stable/tutorial/index.html#making-warnings-more-visible).
This could be done very easily and will already help until the migration to github pages will be done.