Contributing#
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