Enforce striter CI checks for docs and fix some doc issues that would now fail the build.

[cburgdorf]

What was wrong?

The current CI job to validate the docs is to weak. In fact, there are some issues that went under the radar:

1. One JSON code snippet isn't valid JSON which turns off the formatter
2. One doc isn't included in the table of contents

How was it fixed?

1. Make errors fail the build
2. Include full tracebacks in errors
3. Do not use cache to build the docs
4. Add web3.tools.rst to the TOC
5. Fix JSON formatting in example

Todo:

• Add entry to the release notes

Cute Animal Picture

[cburgdorf]

@kclowes would like to ping you for a review on this, too!

[kclowes]

Thanks @cburgdorf! I'm not sure that we want to include the web3.tools docs. I'm pretty sure they're autogenerated and might be more confusing than useful. Pinging @njgheorghita for an opinion, though. Otherwise this is awesome, thank you!

[cburgdorf]

Ah, I see. Yes, it looks like the web3.tools.rst is auto-generated but I'm not sure from where. I'm not a sphinx pro and I haven't auto generated rst files before (we do auto read API docs in Trinity, but the RST files to pick and choose which API docs to read, we create from hand).

Anyway, this would need to be resolved to allow these stricter checks. With the stricter checks that this PR proposes (and which we use for Trinity, Py-EVM, Lahja) rst files that aren't included anywhere are treated as error. So either the automatic generation of this file needs do be prevented or the file needs to be included anywhere.

Feel free to ignore this PR if it doesn't fit into the current approach to docs for this repo. In generally, turning sphinx warnings into errors has worked very well for us so far as it forces you to fix things that are usually worth fixing (like the formatter ignoring that JSON snippet because it doesn't recognize it as valid JSON).

[kclowes]

I like the idea of making sphinx warnings into errors, because it seems like we are constantly dealing with new warnings after fixing them 😆 I'll take a look at how we can stop generating the web3.tools.rst file soon!