Three Cheers for blacken-docs

2021-09-13 Blacken all ye docs.

Black is the de facto standard code formatter for Python, and these days I use it on all my projects. blacken-docs is a tool that also allows you to apply Black to code samples in your docs. I recently rolled it out on my projects to great effect.

blacken-docs was made by the indefatigable Anthony Sottile. It can reformat code samples contained in Markdown, reStructuredText, and LaTeX documents. You can run it as a standalone CLI tool, or under pre-commit (another Anthony Sottile project).

I recently added blacken-docs to my blog, book, and open source projects. Since all projects already used pre-commit, it was easy to add blacken-docs by pasting the hook definition into each project’s .pre-commit-config.yaml.

Blog

I just rebuilt my blog in reStructuredText. As part of this I added blacken-docs, since I want all my code samples to be neat and consistent.

Adding blacken-docs caught a bunch of small errors in my code samples, thanks simply to Black’s syntax validation. These were normally things like missing brackets or incorrect indentation, but also included language mislabeling, such as shell examples highlighted as Python code.

I had to adjust a few examples where I elided part of the code for clarity, since Black requires the example to be syntactically valid. Normally I use ... to represent removed lines of code, but that isn’t always valid. It often is valid Python, as it is the ellipsis literal. In those places that a plain ... doesn’t work, I instead use # ..., for example:

 CACHES = {
     "default": {
-        ...
+        # ...
         "KEY_PREFIX": platform.python_version(),
-        ...
+        # ...
     }
 }

Book

My book uses a similar toolchain, using reStructuredText with Sphinx. Most of my code samples were already formatted with Black, because they live in their own files distributed alongside the book. Relevant fragments are inserted in the text with Sphinx’s handy literalinclude directive. blacken-docs reformatted the few inline examples smoothly.

Open Source

I added blacken-docs to my open source projects about a month ago, using myrepos and this script. This also went well, after some more ellipsis edits.

blacken-docs lead to one project later receiving a somewhat amusing pull request. The author took umbrage with Black’s preference for double quoted strings, so they replaced all double quotes in code samples with single quotes. When they opened the PR, pre-commit.ci ran pre-commit, including the blacken-docs hook. This fixed all the single quotes back to double quotes. pre-commit.ci then automatically committed the change and pushed it back to the PR branch.

This meant when I later opened the PR for review, it had net zero changes!

Fin

If you’re not yet a convert, check out Black today. If you are a convert, take it to the next level with blacken-docs!

—Adam

Learn more about pre-commit in my Git DX book.

One summary email a week, no spam, I pinky promise.

Tags: pre-commit, python