https://github.com/keewis/blackdoc

run black on documentation code snippets
https://github.com/keewis/blackdoc

black codeformatter doctest documentation python

Last synced: 6 months ago
JSON representation

run black on documentation code snippets

• Host: GitHub
• URL: https://github.com/keewis/blackdoc
• Owner: keewis
• License: mit
• Created: 2020-03-09T23:17:55.000Z (over 5 years ago)
• Default Branch: main
• Last Pushed: 2024-10-01T20:22:50.000Z (about 1 year ago)
• Last Synced: 2024-10-11T19:18:46.596Z (12 months ago)
• Topics: black, codeformatter, doctest, documentation, python
• Language: Python
• Homepage: https://blackdoc.readthedocs.io
• Size: 284 KB
• Stars: 47
• Watchers: 2
• Forks: 4
• Open Issues: 10
• Metadata Files:
  • Readme: README.rst
  • License: LICENSE

Awesome Lists containing this project

README

          
blackdoc

========

.. image:: https://github.com/keewis/blackdoc/workflows/CI/badge.svg?branch=main

    :target: https://github.com/keewis/blackdoc/actions

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg

    :target: https://github.com/python/black

.. image:: https://readthedocs.org/projects/blackdoc/badge/?version=latest

    :target: https://blackdoc.readthedocs.io/en/latest/?badge=latest

    :alt: Documentation Status

**blackdoc** is a tool that applies `black`_ to code in documentation.

It was originally a rewrite of a `gist`_ and called

**black-doctest**. In April 2020, it was renamed to **blackdoc**.

.. _gist: https://gist.github.com/mattharrison/2a1a263597d80e99cf85e898b800ec32

.. _black: https://github.com/psf/black

Installation

------------

Dependencies:

- `black`_

- `more-itertools`_

- `rich`_

- `tomli`_

- `pathspec`_

.. _more-itertools: https://github.com/more-itertools/more-itertools

.. _rich: https://github.com/textualize/rich

.. _tomli: https://github.com/hukkin/tomli

.. _pathspec: https://github.com/cpburnz/python-pathspec

Install it with:

.. code:: bash

    python -m pip install blackdoc

Usage

-----

The commandline interface supports two modes: checking and inplace

reformatting.

.. code:: bash

    python -m blackdoc --help

In inplace reformatting mode, it will reformat the doctest lines and

write them back to disk:

.. code:: bash

    # on explicitly mentioned files

    python -m blackdoc file1.py file2.py

    # on the whole directory

    python -m blackdoc .

When checking, it will report the changed files but will not write them to disk:

.. code:: bash

    python -m blackdoc --check .

It is also possible to use the entrypoint script:

.. code:: bash

    blackdoc --help

pre-commit

----------

This repository defines a ``pre-commit`` hook:

.. code:: yaml

   hooks:

   ...

   - repo: https://github.com/keewis/blackdoc

     rev: 3.8.0

     hooks:

     - id: blackdoc

It is recommended to *pin* ``black`` in order to avoid having different versions for each contributor. To automatically synchronize this pin with the version of the ``black`` hook, use the ``blackdoc-autoupdate-black`` hook:

.. code:: yaml

   hooks:

   ...

   - repo: https://github.com/psf/black

     rev: 23.10.1

     hooks:

     - id: black

   ...

   - repo: https://github.com/keewis/blackdoc

     rev: 3.8.0

     hooks:

     - id: blackdoc

       additional_dependencies: ["black==23.10.1"]

     - id: blackdoc-autoupdate-black

Note that this hook is *not* run on ``pre-commit autoupdate``.