Documentation: Imrpove "Contributing" (and amend Sphinx builders)

[dschrempf]

Contains opinionated changes, please check!

I was compiling the documentation using nix build .#docs. Two observations:

1. The Nix build command uses a different sphinx-build command than the one used in docs/Makefile.
2. The Nix build command actually failed because warnings were treated as errors.

So I fixed the warnings (duplicate IDs etc.) and thought, why not use the Makefile to build the documentation also with Nix?
However, that was not easily possible because the Makefile passed on all arguments (i.e., even arguments to the make command itself) to sphinx-build. (I think that is/was actually a bug.)

Anyways, I ended up changing the Makefile in ways that you may not agree with. In particular,

• I added the -n and -W flags to the sphinx-build invocation (warnings are errors).
• I removed the help target which seemed a bit unnecessary and overcomplicates things.
• I added a single html target to build the documentaiton using the HTML builder.

Have a look and let me know what you think!

[dschrempf]

The "Contributing" help page also states that

The documentation is also built and previewed on every PR

but I could not find any GitHub Action/workflow doing so. Maybe this information is outdated and should be removed?

[fendor]

Thanks for the PR!

The docs are built for each PR:

I was able to look at the docs and verify the links are still working

[fendor]

LGTM! I appreciate the consistency in naming.

[michaelpj]

LGTM!