Skip to content

Commit

Permalink
Merge pull request #1648 from opensafely-core/steve/check-complete-eh…
Browse files Browse the repository at this point in the history
…rql-dataset-definitions-in-docs

test: Check complete ehrQL dataset definitions in docs
  • Loading branch information
StevenMaude authored Nov 7, 2023
2 parents 9e3bb6c + ec7f61e commit aeec978
Show file tree
Hide file tree
Showing 11 changed files with 779 additions and 91 deletions.
47 changes: 47 additions & 0 deletions DEVELOPERS.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ Tests are divided into the following categories.
<dt>acceptance</dt><dd>tests which demonstrate how ehrQL is used and check compatibility with real studies</dd>
<dt>integration</dt><dd>tests of detailed code logic that require a database</dd>
<dt>docker</dt><dd>tests of the ehrQL docker image</dd>
<dt>docs</dt><dd>tests of the documentation examples</dd>
</dl>

Each category lives in its own directory (for example `tests/unit`) and has its own `just` command to run it (for
Expand Down Expand Up @@ -299,6 +300,52 @@ generated markdown files. It is a developer's responsibility to update the gener
their PR if required. There is also a CI step that will check that the documentation is up to
date.

### Testing dataset definitions included in the documentation

All of the example tests can be run with:

just test-docs-examples

* Examples to be tested run with `generate_dataset()`.
* Dataset definitions may be included inline in Markdown files in `docs/`,
labelled as code blocks with the `ehrql` syntax,
or as Python `.py` files in `docs/`.

#### Examples using `codelist_from_csv()`

For testing examples,
`codelist_from_csv()` is currently patched out to work without any CSV,
nor are codelist codes validated.

The function signature of `codelist_from_csv()` calls from examples *is* checked.

This may be improved in future to make the testing more rigorous;
see #1694.

#### Inline code blocks (Markdown fences)

Examples in the documentation Markdown source will be tested as part of the test suite
if you place complete examples in a code block with the `ehrql` syntax label: `` ```ehrql ``

This will still highlight the code as if it were Python.

:warning: The `ehrql` syntax label is for inline and complete ehrQL blocks only.

We use the SuperFences extension for extracting Markdown fences.
Refer to the [SuperFences documentation](https://facelessuser.github.io/pymdown-extensions/extensions/superfences/#nested-fence-format) for more details of the fence format.

#### Dataset definitions as included Python files

Python files in the `docs/` directory are assumed to be working dataset definitions.

They are also tested in the test suite.

If included in the documentation using the snippet syntax,
they must be used with a `python` syntax label.
(If they were labelled as `ehrql`,
the snippet line itself would be extracted from the Markdown,
and treated as a dataset definition.)

### Updating the main OpenSAFELY documentation repository

Merges to the main branch in this repo trigger a [deployment of the main OpenSAFELY documentation via a Github Action](https://github.com/opensafely-core/ehrql/actions/workflows/deploy-documentation.yml).
4 changes: 4 additions & 0 deletions Justfile
Original file line number Diff line number Diff line change
Expand Up @@ -180,6 +180,10 @@ test-backend-validation *ARGS: devenv
test-docker *ARGS: devenv
$BIN/python -m pytest tests/docker {{ ARGS }}

# Run the docs examples tests only. Optional args are passed to pytest.
test-docs-examples *ARGS: devenv
$BIN/python -m pytest tests/docs {{ ARGS }}

# Run the integration tests only. Optional args are passed to pytest.
test-integration *ARGS: devenv
$BIN/python -m pytest tests/integration {{ ARGS }}
Expand Down
2 changes: 1 addition & 1 deletion docs/explanation/running-ehrql.md
Original file line number Diff line number Diff line change
Expand Up @@ -187,7 +187,7 @@ to produce an output file that you can inspect.
into a new file called `dataset_definition.py`
and save it in your `learning-ehrql` directory:

```python
```ehrql
from ehrql import create_dataset
from ehrql.tables.beta.core import patients, medications
Expand Down
Loading

0 comments on commit aeec978

Please sign in to comment.