Documentation is more important than most people are willing to admit. If you want your project to be used though, you to invest in it. As a bonus, you might also be able to get some good unit tests for free too. In this series of video's we'll highlight how we've set up documentation for clumper.
This is the contents of
test_docstring.py at the time of making this video:
import pytest from clumper import Clumper from clumper.sequence import row_number, smoothing, expanding, rolling, impute def handle_docstring(doc, indent): """ This function will read through the docstring and grab the first python code block. It will try to execute it. If it fails, the calling test should raise a flag. """ if not doc: return start = doc.find("```python\n") end = doc.find("```\n") if start != -1: if end != -1: code_part = doc[(start + 10) : end].replace(" " * indent, "") print(code_part) exec(code_part) @pytest.mark.parametrize("m", [m for m in dir(Clumper) if not m.startswith("_")]) def test_clumper_docstrings(m): """ Take the docstring of every method on the `Clumper` class. The test passes if the usage examples causes no errors. """ handle_docstring(getattr(Clumper, m).__doc__, indent=8) @pytest.mark.parametrize("m", [row_number, smoothing, expanding, rolling, impute]) def test_mappers_docstrings(m): """ Take the docstring of every method on the `Clumper` class. The test passes if the usage examples causes no errors. """ handle_docstring(m.__doc__, indent=4)
indent still makes this approach sligthly hacky but the nice thing is
that the documentation now allows us to easily write a unit test for each
method that we've implemented. You can even see each method being tested by
pytest tests/test_documentation/test_docstring.py --verbose
Feedback? See an issue? Something unclear? Feel free to mention it here.
If you want to be kept up to date, consider signing up for the newsletter.