📝 Add gen test documentation generation

[wenceslas-sanchez]

Hi @hwwhww 🖖

The goal of this PR is to propose a generator of test documentation for this repo.

This code is a copy/paste (with adaptations) of the execution-spec-tests of the gen_test_case_reference.py` file. It generates markdown file from tests usable for the documentation website.

How it works:

It looks for test files at tests\core\pyspec\eth2spec\test and generate a documentation with a command line to be used to run the tests.
Any docstring in a test will be displayed (there is no docstring for the moment).

In the CD, it will generates a folder tests in in docs/ with the below structure:

Issue

For the moment, I can't figure how to make the import from tests.core.eth2spec.test.helpers.constants import ALL_PHASES without pycharm; maybe we will have to move this code to the tests folder. If you have an idea I will take it.

TODO:

• enable CD (build docs/tests within the Github Action)
• refacto variable names (for instance fixture is not a word used in consensus-specs)
• tests ?

[hwwhww]

@wenceslas-sanchez

For the moment, I can't figure how to make the import from tests.core.eth2spec.test.helpers.constants import ALL_PHASES without pycharm; maybe we will have to move this code to the tests folder. If you have an idea I will take it.

What do you mean by pycharm (IDE?) here?

I think of two solutions:

1. We can install pyspec during building docs: move gen_test_case_reference.py to consensus-specs/scripts folder. You can pick the code from Debug tools for loading SSZ object from file #3355, where I created a requirements.txt so we can install the package with pip3 install -r requirements.txt command.
2. If ALL_PHASES is the only variable we need... maybe write a parser to get all SpecForkName(<VALUE>) values? Hacky though 😅

[wenceslas-sanchez]

1. ip3 install -r requirements.txt

I think the first option is the easiest; that's what I implemented within the .github/workflows/docs.yml. Do you have a way to test the CD ?

[hwwhww]

@wenceslas-sanchez

Do you have a way to test the CD ?

Unfortunately, not an elegant way: I tested it with my personal repo GitHub Pages. 😓

Basic setting as below:

[wenceslas-sanchez]

@wenceslas-sanchez

Do you have a way to test the CD ?

Unfortunately, not an elegant way: I tested it with my personal repo GitHub Pages. 😓

Basic setting as below:

I tried within my local version of the repo, but I can't find a way to generate the documentation. That's because I fail to install './[test]' for eth2spec.
If we run this (in the Github Action) pip install -r scripts/requirements.txt, we have this error; the subprocess can't install ruamel.yaml

Even forcing the install of ruamel + marko (in the Github Action), we still have the issue but for marko only now... see this error

Since you interacted a lot with setup.py within Github Action, maybe you will find the issue ... I updated the docs.yml I used in this branch.