Contributing#

Github-CI Coverage Status Documentation Status Code style: black

We welcome all contributions! See the EBP Contributing Guide for general details, and below for guidance specific to MyST-Parser.

1.  Install for development#

To install myst-parser for development, take the following steps:

git clone https://github.com/executablebooks/MyST-Parser
cd MyST-Parser
git checkout master
pip install -e .[code_style,linkify,testing,rtd]

2.  Code Style#

Code style is tested using flake8, with the configuration set in .flake8, and code formatted with black.

Installing with myst-parser[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-Parser
>> pre-commit install

Optionally you can run black and flake8 separately:

>> 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 preferred docstring format is outlined in MyST-Parser/docstring.fmt.mustache and can be used automatically with the autodocstring VS Code extension.

3.  Testing#

For code tests, myst-parser uses pytest:

>> cd MyST-Parser
>> 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-Parser
>> tox

For documentation build tests:

>> cd MyST-Parser/docs
>> make clean
>> make html-strict