Development

Linting and checks

Use pip to install pre-commit and then use pre-commit install to install the pre-commit hook for the repository.

Creating a new formatter

• Implement a Formatter by inheriting from pydocstringformatter.formatting.Formatter.

• Add your new formatter to pydocstringformatter.formatting.FORMATTERS.

• Write a clear docstring because this will be user-facing: it’s what will be seen in the help message for the formatter’s command line option.

• Choose a proper name because this will be user-facing: the name will be used to turn the formatter on and off via the command line or config files.

• Rebuild the documentation by running:

cd docs
make html

Testing

To run all the tests:

pytest

To create test for a specific formatting option use the tests/data/format directory. For each .py file create a .py.out file with the expected output after formatting. The test suite will automatically pickup the new tests.

To only run a specific test from that directory, for example tests/data/format/multi_line/class_docstring.py, use:

pytest -k multi_line-class_docstring

Primer

To check if any changes create any unforeseen regressions all pull requests are tested with our primer. This process is heavily inspired on other open source projects and our own primer is based on the one used by mypy.

You can also run the primer locally with minimal set-up. First you will need to make a duplicate of your pydocstringformatter directory in a new ./program_to_test directory. This is required so that the primer can check out multiple versions of the program and compare the difference.

The next step is to follow the bash script in the Run primer step in the primer workflow file, found at .github/workflows/primer.yaml. This should allow you to run all necessary steps locally.

The final output of the primer run can be found in .pydocstringformatter_primer_tests/fulldiff.txt

New projects to run the primer over can be added to the pydocstringformatter/testutils/primer/packages.py file.