pre_commit

Sphinx extension to show examples of .pre-commit-config.yaml configuration.

New in version 1.6.0.

Enable sphinx_toolbox.pre_commit by adding the following to the extensions variable in your conf.py:

extensions = [
    ...
    'sphinx_toolbox.pre_commit',
    ]

For more information see https://www.sphinx-doc.org/en/master/usage/extensions#third-party-extensions .

Usage

.. pre-commit::

Directive which shows an example snippet of .pre-commit-config.yaml.

:rev: (string)

The revision or tag to clone at.

:hooks: (comma separated list)

A list of hooks IDs to document.

If not given the hooks will be parsed from .pre-commit-hooks.yaml.

:args: (comma separated list)

A list arguments that should or can be provided to the first hook ID.

New in version 1.7.2.

Example

.. pre-commit::
    :rev: v0.0.4
    :hooks: some-hook,some-other-hook

- repo: https://github.com/sphinx-toolbox/sphinx-toolbox
  rev: v0.0.4
  hooks:
  - id: some-hook
  - id: some-other-hook

.. pre-commit:flake8:: version

Directive which shows an example snippet of .pre-commit-config.yaml for a flake8 plugin.

The directive takes a single argument – the version of the flake8 plugin to install from PyPI.

:flake8-version: (string)

The version of flake8 to use. Default 3.8.4.

:plugin-name: (string)

The name of the plugin to install from PyPI. Defaults to the repository name.

Example

.. pre-commit:flake8:: 0.0.4

- repo: https://github.com/pycqa/flake8
  rev: 3.8.4
  hooks:
  - id: flake8
    additional_dependencies:
    - sphinx-toolbox==0.0.4

Changed in version 2.8.0: The repository URL now points to GitHub.

API Reference

Classes:

Flake8PreCommitDirective(name, arguments, …)

A Sphinx directive for documenting flake8 plugins’ pre-commit hooks.

PreCommitDirective(name, arguments, options, …)

A Sphinx directive for documenting pre-commit hooks.

Functions:

parse_hooks(hooks)

Parses the comma, semicolon and/or space delimited list of hook IDs.

setup(app)

Setup sphinx_toolbox.pre_commit.

class Flake8PreCommitDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Bases: SphinxDirective

A Sphinx directive for documenting flake8 plugins’ pre-commit hooks.

class PreCommitDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Bases: SphinxDirective

A Sphinx directive for documenting pre-commit hooks.

parse_hooks(hooks)[source]

Parses the comma, semicolon and/or space delimited list of hook IDs.

Parameters

hooks (str)

Return type

List[str]

setup(app)[source]

Setup sphinx_toolbox.pre_commit.

Parameters

app (Sphinx) – The Sphinx application.

Return type

SphinxExtMetadata