Usage

blackdoc tries to copy as much of the CLI of black as possible. This means that most calls to black can be directly translated to blackdoc:

To reformat specific files, use:

python -m blackdoc file1 file2 ...

while passing directories reformats all files in those directories that match the file format specified by --include and --exclude:

python -m blackdoc directory1 directory2 ...

mixing directories and files is also possible.

As an example, having a structure like:

directory
├── file.py
└── file.rst

with

# directory/file.py
"""
docstring with code.

doctests:
>>> s={ "a", "b","c", 'd', "e", "f", "e",
...     "f", "g",'h', "i", "j", "k",'l', 'm',
...                                          }

ipython:
In [1]: d= { "a": 0, "b": 1, "c": 2,
   ...: "d": 3, "e": 4, "f": 5, "g": 6,
   ...: "h": 7, "i": 8, "j": 9 }
"""
.. directory/file.rst
file with code:

.. code:: python

    def function_with_long_name(parameter1, parameter2,
          parameter3, *variable_args, **keyword_args):
        pass

more code:

.. code-block:: python

    for index, (value1, value2, value3, value4) in enumerate(zip(iterable1,
            iterable2, iterable3, iterable4)):
        pass

executed code:

.. ipython:: python

    keys = ('key1', 'key2')
    values = (15,4)

    mapping = dict(zip(keys, values))

    mapping

with explicit grouping:

.. ipython:: python

    In [1]: keys = ( 'key1', 'key2' )
       ...: values = {15, 4}

    In [2]: mapping = {key : value for key, value in zip( keys,values) }
       ...: mapping

with testcode:

.. testsetup::

   x = 'X'
   y =  "Y"

.. testcode::

   assert x==x
   assert x !=  y

.. testcleanup::

   print('test completed')

If we run

python -m blackdoc directory

we get

# directory/file.py
"""
docstring with code.

doctests:
>>> s = {
...     "a",
...     "b",
...     "c",
...     "d",
...     "e",
...     "f",
...     "e",
...     "f",
...     "g",
...     "h",
...     "i",
...     "j",
...     "k",
...     "l",
...     "m",
... }

ipython:
In [1]: d = {"a": 0, "b": 1, "c": 2, "d": 3, "e": 4, "f": 5, "g": 6, "h": 7, "i": 8, "j": 9}
"""
.. directory/file.rst
file with code:

.. code:: python

    def function_with_long_name(
        parameter1, parameter2, parameter3, *variable_args, **keyword_args
    ):
        pass

more code:

.. code-block:: python

    for index, (value1, value2, value3, value4) in enumerate(
        zip(iterable1, iterable2, iterable3, iterable4)
    ):
        pass

executed code:

.. ipython:: python

    keys = ("key1", "key2")
    values = (15, 4)

    mapping = dict(zip(keys, values))

    mapping

with explicit grouping:

.. ipython:: python

    In [1]: keys = ("key1", "key2")
       ...: values = {15, 4}

    In [2]: mapping = {key: value for key, value in zip(keys, values)}
       ...: mapping

with testcode:

.. testsetup::

    x = "X"
    y = "Y"

.. testcode::

    assert x == x
    assert x != y

.. testcleanup::

    print("test completed")

If instead we run

python -m blackdoc --check directory

the result is:

would reformat directory/file.rst
would reformat directory/file.py
Oh no! 💥 💔 💥
2 files would be reformatted.

with a non-zero exit status.