Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(docs): re-write test gen doc flow with pytest plugin #801

Merged
merged 13 commits into from
Sep 23, 2024

Conversation

danceratopz
Copy link
Member

@danceratopz danceratopz commented Sep 16, 2024

🗒️ Description

This is a rewrite of the automatic test case doc generation as a pytest plugin (as apposed to a standalone script). A preview is available at https://ethereum.github.io/execution-spec-tests/pr-801-preview.

Doc Improvements

  1. Test module pages: Added a table that provides and overview of its test functions, e.g., tests/prague/eip2537_bls_12_381_precompiles/test_bls12_g1add.
  2. Added test function pages which include a table which tries to give an overview of its parametrized test cases, e.g., tests/prague/eip2537_bls_12_381_precompiles/test_bls12_g1add::test_valid.
  3. Added static html files for the tables of the function parameters overview, as they often don't play well within mkdocs styling.
  4. Markdown pages: Added a header with a path and ref link for the markdown file, e.g., tests/prague/eip7692_eof_v1/tracker.md

Technical Improvements

  1. Doc build fails if no function docstring is available or the test type (e.g. state_test) can not be determined (both used in the function overview tables on test module pages).
  2. Using a pytest plugin allows us to lever all the usual pytest flags for test item filtering and fork specification (great for debugging) and to introspect test items to easily grab test metadata.
  3. jinja2 is used for templating, which helps separate the content from its formatting. Jinja is a very powerful templating library which helps save a lot of boilerplate code.

🔗 Related Issues

Perhaps solved, plz check whether the styling is acceptable, e.g., test_bls12_g1add/test_valid.html.

Current issues:

Ideas for future improvements:

✅ Checklist

  • All: Set appropriate labels for the changes.
  • All: Considered squashing commits to improve commit history.
  • All: Added an entry to CHANGELOG.md.
  • All: Considered updating the online docs in the ./docs/ directory.
  • Tests: All converted JSON/YML tests from ethereum/tests have been added to converted-ethereum-tests.txt.
  • Tests: A PR with removal of converted JSON/YML tests from ethereum/tests have been opened.
  • Tests: Included the type and version of evm t8n tool used to locally execute test cases: e.g., ref with commit hash or geth 1.13.1-stable-3f40e65.
  • Tests: Ran mkdocs serve locally and verified the auto-generated docs for new tests in the Test Case Reference are correctly formatted.

@danceratopz danceratopz added scope:docs Scope: Documentation type:feat type: Feature labels Sep 16, 2024
Copy link
Member

@marioevz marioevz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is absolutely amazing, great PR!
Just some minor comments. Thanks!

src/pytest_plugins/filler/gen_test_doc/gen_test_doc.py Outdated Show resolved Hide resolved
src/pytest_plugins/filler/gen_test_doc/gen_test_doc.py Outdated Show resolved Hide resolved
src/pytest_plugins/filler/gen_test_doc/page_props.py Outdated Show resolved Hide resolved
danceratopz and others added 2 commits September 23, 2024 07:14
Co-authored-by: Mario Vega <marioevz@gmail.com>
Disable duplicate docstrings warning for this PR though
@danceratopz danceratopz merged commit ad69c4b into main Sep 23, 2024
7 checks passed
@danceratopz danceratopz deleted the feat/docs/test-doc-gen-as-pytest-plugin branch September 23, 2024 06:24
danceratopz added a commit that referenced this pull request Sep 26, 2024
Co-authored-by: Mario Vega <marioevz@gmail.com>
danceratopz added a commit that referenced this pull request Sep 27, 2024
Co-authored-by: Mario Vega <marioevz@gmail.com>
danceratopz added a commit that referenced this pull request Oct 3, 2024
Co-authored-by: Mario Vega <marioevz@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
scope:docs Scope: Documentation type:feat type: Feature
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants