Create CI-only docs builds for additional formats, update docs Makefile, add deletion of unused autogen docs

[pacrob]

What was wrong?

Build on RTD has been failing, but only when a PR is merged into main. In our own docs testing, we only test building the html version of the docs, but for several months now we've had RTD building html, pdf, and epub versions for almost all our libs. It seems like there hasn't been an issue, but in this case the html docs build fine but the epub build fails.

How was it fixed?

Created a new validate-docs-ci make command, which will build pdf and epub only as part of CI. Tried changing it so all docs building builds all 3 formats, but the local reqs for building latexpdf are hefty.

Fix issues with epub build by restructuring the introduction and guides so that the quickstart.rst (now installation.rst is only included once.

Updated docs/Makefile to template version(not sure why that didn't happen in the recent general update) and added to the docs Makefile clean directive to specifically delete the autogenerated docs we don't use.

Todo:

• Clean up commit history

• Add or update documentation related to these changes

• Add entry to the release notes

Cute Animal Picture

[kclowes]

Right now with the dev/doc dependencies installed, running make docs locally is failing. I think we'll need to add a few dependencies to either docs or dev deps.

[pacrob]

Right now with the dev/doc dependencies installed, running make docs locally is failing. I think we'll need to add a few dependencies to either docs or dev deps.

I had to install the latex dependencies locally for it to build properly. My requirements were the same latexmk, tex-gyre, and texlive-fonts-extra from CI config. Not sure what it would be for mac. What's the error message you're seeing?

Edit: discussed, the install requirements for building latex locally are pretty hefty. Defining a CI-only docs build in Makefile.

[fselmo]

Did this come from somewhere as a template? Can you add a reference if so.

[pacrob]

Indeed! From the python project template:

https://github.com/ethereum/ethereum-python-project-template/blob/main/docs/Makefile

[fselmo]

lgtm 💯

[reedsa]

Looks good here. Approving, but did notice a prexisting issue with the docs build.

I was looking at the failing docs badge and turns out there's an error importing a sphinx extension. There was minimal information I could find related to the version we're using, pinned to 0.2.0 due to 0.3.0 causing another error.

Any idea what could fix this issue?

Running Sphinx v6.2.1

Extension error:
Could not import extension sphinxcontrib.asyncio (exception: cannot import name 'PyModulelevel' from 'sphinx.domains.python' (/Users/reedsa/.pyenv/versions/3.10.12/envs/py-evm/lib/python3.10/site-packages/sphinx/domains/python.py))
make[1]: *** [html] Error 2
make: *** [build-docs] Error 2

[kclowes]

Looks good to me!