Contribute to MyST-NB¶
We welcome all contributions! See the EBP Contributing Guide for general details, and below for guidance specific to MyST-NB.
MyST-NB for package development:
git clone https://github.com/executablebooks/MyST-NB cd MyST-NB git checkout master pip install -e .[code_style,testing,rtd]
How the Jupyter Notebook parser works¶
MyST-NB is built on top of the MyST markdown parser. This is a flavor of markdown designed to work with the Sphinx ecosystem. It is a combination of CommonMark markdown, with a few extra syntax pieces added for use in Sphinx (for example, roles and directives).
MyST-NB will do the following:
Check for any pages in your documentation folder that end in
.ipynb. For each one:
Loop through the notebook’s cells, converting cell contents into the Sphinx AST.
If it finds executable code cells, include their outputs in-line with the code.
If it finds markdown cells, use the MyST parser to convert them into Sphinx.
Eventually, it will also provide support for writing pure-markdown versions of notebooks that can be executed and read into Sphinx.
myst-nb[code_style] makes the pre-commit
package available, which will ensure this style is met before commits are submitted, by reformatting the code
and testing for lint errors.
It can be setup by:
>> cd MyST-NB >> pre-commit install
Optionally you can run
>> black . >> flake8 .
Editors like VS Code also have automatic code reformat utilities, which can adhere to this standard.
All functions and class methods should be annotated with types and include a docstring. The prefered docstring format is outlined in
MyST-NB/docstring.fmt.mustache and can be used automatically with the
autodocstring VS Code extension.
For code tests, MyST-NB uses pytest):
>> cd MyST-NB >> pytest
You can also use tox, to run the tests in multiple isolated environments (see the
tox.ini file for available test environments):
>> cd MyST-NB >> tox
For documentation build tests:
>> cd MyST-NB >> tox
>> cd MyST-NB/docs >> make clean >> make html-strict
Testing is one of the most important aspects of your PR. You should write test cases and verify your implementation by following the testing guide above. If you modify code related to existing unit tests, you must run appropriate commands and confirm that the tests still pass.
To run tests along with coverage:
pytest -v --cov=myst_nb
To run tests along with generation of an html coverage report:
pytest -v --cov=myst_nb --cov-report=html
Test File and Directory Naming Conventions¶
Tests are found in the tests directory. In order for
pytest to find the test scripts correctly, the name of each test script should start with
How to Write Tests¶
There are many examples of unit tests under the tests directory, so reading some of them is a good and recommended way. Prefer using the
fixtures and the classes defined in conftest.py as much as possible.
If using pytest-regression, a new directory with
test_ prefix is expected to be created in the first test run. This will store your expected output against which subsequent test outputs will be compared.