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)

Bases: SphinxDirective

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

has_content = False

Type:    bool

option_spec = {'flake8-version': <class 'str'>, 'plugin-name': <class 'str'>}

Type:    dict

required_arguments = 1

Type:    int

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

Bases: SphinxDirective

A Sphinx directive for documenting pre-commit hooks.

has_content = False

Type:    bool

option_spec = {'args': <function parse_hooks>, 'hooks': <function parse_hooks>, 'rev': <class 'str'>}

Type:    dict

parse_hooks(hooks)

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

Parameters:

hooks (str)

Return type:

List[str]

setup(app)

Setup sphinx_toolbox.pre_commit.

Parameters:

app (Sphinx) – The Sphinx application.

Return type:

SphinxExtMetadata