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

Implement basic support for documentation tests #1971

Closed
wants to merge 6 commits into from

Conversation

etalian
Copy link

@etalian etalian commented Aug 9, 2022

From the outside, it is currently very hard to find out how much of the syntax described in the documentation is actually implemented by the Explorer (as also evidenced by #1891). And even if this was known, documentation and implementation are likely to drift over time as things evolve.

This PR provides:

  • a (very) minimal inline DSL to transform Markdown fenced code blocks into runnable tests
  • a py_binary target implementing the above DSL
  • enough Bazel plumbing to make bazel test docs/... automatically generate and execute these tests

The idea would then be, over time, to mark (at least some of) the example code in the documentation as tests, and have Bazel test automatically that the syntax used in the documentation is in fact valid.

TODO

  • better error handling (when a test fails, it's very hard to see why and trace the failure back to the corresponding Markdown line)
  • review by someone with Bazel readability (I never used Bazel before yesterday, there might be better ways to generate targets and tests dynamically)
  • friendlier DSL syntax (plus possibly some heuristics to avoid having to write it at all whenever possible)

@etalian etalian force-pushed the etalian/doctests branch 2 times, most recently from 954549f to 2fa16ac Compare August 9, 2022 23:14
@github-actions
Copy link

We triage inactive PRs and issues in order to make it easier to find active work. If this PR should remain active, please comment or remove the inactive label.
This PR is labeled inactive because the last activity was over 90 days ago. This PR will be closed and archived after 14 additional days without activity.

@github-actions github-actions bot added the inactive Issues and PRs which have been inactive for at least 90 days. label Nov 26, 2022
@github-actions
Copy link

We triage inactive PRs and issues in order to make it easier to find active work. If this PR should remain active or becomes active again, please reopen it.
This PR was closed and archived because there has been no new activity in the 14 days since the inactive label was added.

@github-actions github-actions bot closed this Dec 11, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
inactive Issues and PRs which have been inactive for at least 90 days.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant