Updating the documentation
OpenSAFELY is a rapidly changing platform and the user documentation should be updated frequently to keep pace. If you are an OpenSAFELY user and want to contribute corrections, clarifications, or new materials to the documentation, please do! You can either:
- Suggest improvements in an issue.
- Clone the repo locally, make edits on a new branch, then create a pull request for it.
- Edit directly on GitHub (instructions), making sure to "Create a new branch for this commit and start a pull request".
Do not commit changes directly to the main branch.
Documentation style🔗
When adding or revising text, use Semantic Line Breaks rather than fixed length lines. With semantic line breaks, the diff is more concise and easier to interpret than with fixed length lines, where a single change can propagate through a whole paragraph.
Making changes to the study definition variables🔗
Edit the docstrings in the patients.py file in the cohort-extractor repository.
Variable docstrings follow the Google style guide.
If you don't have write access, you can fork the cohort-extractor repo, make a change, and submit a pull request.
Editing directly in GitHub will take you through these steps automatically.
At least one commit in the pull request should be named using the prefix fix: or feature:. For example fix: typo in age_as_of docstring.
This ensures that a new version of cohortextractor is released and can be imported by the documentation via GitHub actions.
Then add a reference to your new variable in the variables page.
Additionally, the
requirements.prod.txt
file in the documentation
repo itself has to be
updated to match the new incremented version of cohortextractor. See
the documentation repository's
README
that details the use of pip-compile for this.
Making changes to the dataset definition examples🔗
You will need to check out the documentation repo so you can run the example generating toolchain.
Edit the python modules in the databuilder/snippets directory.
Each example is bounded by snex markers which define the filename they will produce.
For example, a block starting with :snippet dataset-definition will create the file examples/src-dataset-definition.md.
All example filenames are prefixed with src-
Once you've edited an example (or created a new one) you can run just databuilder/extract to update the markdown files in examples.
Examples are included in the markdown files using the pymdown snippet notation.
Make sure you commit both the changes to the examples and databuilder/snippets directories.
If you are updating multiple examples it might be easier to the extraction step happen each time you change the python modules, you can do this with just databuilder/watch-examples.
Updating Data Builder backend, contract and reference documentation🔗
If a new Data Builder version is released that updates Data Builder's backend, contract and reference documentation, there should be an automated pull request opened in the documentation repository to keep it synchronised.