Contributing

Thank you for your interest in improving this acronym filter for Pandoc. Pandoc-acro is open sourced under the BSD 2-Clause License and welcomes feedback via bug reports, feature requests, and pull requests. Please report all bugs or request a feature by submitting an issue on the Github project page.

Reporting Issues

When submitting a bug report on Github, please include as much information as possible to allow us to figure out what is happening. Please try to include the Python version, the Panflute version, an explanation of your input(s) and the expected output, and a minimal example demonstrating issue.

Pull Requests

  • Follow PEP 8 with numpy docstrings

  • Update the documentation as appropriate

  • Update the Changelog

  • Provide a test demonstrating the error is fixed or the new feature works as expected if appropriate

  • Pull requests should be against the trunk branch

The development uses nox to aide with testing multiple Python versions and linting the code and documentation. It uses the conda back end to manage the virtual environment to make sure Pandoc is available. Therefore, you must have conda on your search path for nox to succeed. To run the full suite (that must all pass), use

nox -x

To run an individual session, use the --session option to nox. The available sessions are:

  • flake8 to run flake8

  • mypy to run mypy

  • docs to run Sphinx on the documentation tree

  • test-3.X where X is a supported minor version of Python

The test sessions also accept additional arguments that can be passed to pytest. For example, to run test_get_key.py and launch the debugger on error use

nox -s test-3.8 -- --pdb tests/test_get_key.py

Deploying the HTML Documentation

The HTML version of the documentation can be updated by running nox with the docs session. Then add and commit the changes. To prevent pushing the stable branch without rebuilding the documentation, copy the script pre-push-build-sphinx.py to .git/hooks/pre-push and make it executable.