ethereum / py-evm

A Python implementation of the Ethereum Virtual Machine
https://py-evm.readthedocs.io/en/latest/
MIT License
2.26k stars 650 forks source link

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

Closed pacrob closed 8 months ago

pacrob commented 8 months ago

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:

Cute Animal Picture

image

pacrob commented 8 months ago

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.