repo_helper.blocks

Reusable blocks of reStructuredText.

Classes:

ShieldsBlock(username, repo_name, version, *)

Create the shields block for insertion into the README, documentation etc.

Functions:

create_docs_install_block(repo_name, username)

Create the installation instructions for insertion into the documentation.

create_docs_links_block(username, repo_name)

Create the documentation links block.

create_readme_install_block(modname, username)

Create the installation instructions for insertion into the README.

create_short_desc_block(short_desc)

Creates the short description block insertion into the README, documentation etc.

get_docs_installation_block_template()

Loads the docs_installation_block template from file and returns a jinja2 jinja2.environment.Template for it.

get_docs_links_block_template()

Loads the docs_links_block template from file and returns a jinja2 jinja2.environment.Template for it.

get_readme_installation_block_no_pypi_template()

Loads the readme_installation_block_no_pypi template from file and returns a jinja2 jinja2.environment.Template for it.

get_readme_installation_block_template()

Loads the readme_installation_block template from file and returns a jinja2 jinja2.environment.Template for it.

Data:

installation_regex

Regular expression to match the installation block placeholder.

links_regex

Regular expression to match the links block placeholder.

shields_regex

Regular expression to match the shields block placeholder.

short_desc_regex

Regular expression to match the short description block placeholder.

class ShieldsBlock(username, repo_name, version, *, conda=True, tests=True, docs=True, docs_url='https://{}.readthedocs.io/en/latest/?badge=latest', pypi_name=None, unique_name='', docker_shields=False, docker_name='', platforms=None, pre_commit=False, on_pypi=True, primary_conda_channel=None)[source]

Bases: object

Create the shields block for insertion into the README, documentation etc.

Parameters
  • username (str) – The username of the GitHub account that owns the repository.

  • repo_name (str) – The name of the repository.

  • version (Union[str, int])

  • conda (bool) – Default True.

  • tests (bool) – Default True.

  • docs (bool) – Default True.

  • docs_url (str) – Default 'https://{}.readthedocs.io/en/latest/?badge=latest'.

  • pypi_name (Optional[str]) – The name of the project on PyPI. Defaults to the value of repo_name if unset. Default None.

  • unique_name (str) – An optional unique name for the reST substitutions. Default ''.

  • docker_shields (bool) – Whether to show shields for Docker. Default False. Default False.

  • docker_name (str) – The name of the Docker image on DockerHub. Default ''.

  • platforms (Optional[Iterable[str]]) – List of supported platforms. Default None.

  • on_pypi (bool) – Default True.

  • primary_conda_channel (Optional[str]) – The Conda channel the package can be downloaded from. Default None.

New in version 2020.12.11.

Methods:

make()

Constructs the contents of the shields block.

set_docs_mode()

Create shields for insertion into Sphinx documentation.

set_readme_mode()

Create shields for insertion into README.rst.

Attributes:

sections

This list controls which sections are included, and their order.

substitutions

This list controls which substitutions are included, and their order.

make()[source]

Constructs the contents of the shields block.

Return type

StringList

sections = ('Docs', 'Tests', 'PyPI', 'Anaconda', 'Activity', 'QA', 'Docker', 'Other')

Type:    tuple

This list controls which sections are included, and their order.

set_docs_mode()[source]

Create shields for insertion into Sphinx documentation.

set_readme_mode()[source]

Create shields for insertion into README.rst.

substitutions = ('docs', 'docs_check', 'actions_linux', 'actions_windows', 'actions_macos', 'actions_flake8', 'actions_mypy', 'requires', 'coveralls', 'codefactor', 'pypi-version', 'supported-versions', 'supported-implementations', 'wheel', 'conda-version', 'conda-platform', 'license', 'language', 'commits-since', 'commits-latest', 'maintained', 'pypi-downloads', 'docker_build', 'docker_automated', 'docker_size')

Type:    tuple

This list controls which substitutions are included, and their order.

create_docs_install_block(repo_name, username, conda=True, pypi=True, pypi_name=None, conda_channels=None)[source]

Create the installation instructions for insertion into the documentation.

Parameters
  • repo_name (str) – The name of the GitHub repository.

  • username (str) – The username of the GitHub account that owns the repository. (Not used; ensures API compatibility with create_readme_install_block())

  • conda (bool) – Whether to show Anaconda installation instructions. Default True.

  • pypi (bool) – Whether to show PyPI installation instructions. Default True.

  • pypi_name (Optional[str]) – The name of the project on PyPI. Defaults to the value of repo_name if unset. Default None.

  • conda_channels (Optional[Sequence[str]]) – List of required Conda channels. Default None.

Return type

str

Returns

The installation block created from the above settings.

Create the documentation links block.

Parameters
  • username (str) – The username of the GitHub account that owns the repository.

  • repo_name (str) – The name of the GitHub repository.

Return type

str

Returns

The documentation links block created from the above settings.

create_readme_install_block(modname, username, conda=True, pypi=True, pypi_name=None, conda_channels=None)[source]

Create the installation instructions for insertion into the README.

Parameters
  • modname (str) – The name of the program / library.

  • username (str) – The username of the GitHub account that owns the repository.

  • conda (bool) – Whether to show Anaconda installation instructions. Default True.

  • pypi (bool) – Whether to show PyPI installation instructions. Default True.

  • pypi_name (Optional[str]) – The name of the project on PyPI. Defaults to the value of repo_name if unset. Default None.

  • conda_channels (Optional[Sequence[str]]) – List of required Conda channels. Default None.

Return type

str

Returns

The installation block created from the above settings.

create_short_desc_block(short_desc)[source]

Creates the short description block insertion into the README, documentation etc.

Parameters

short_desc (str) – A short description of the program / library.

Return type

str

Returns

The short description block created from the above settings.

get_docs_installation_block_template()[source]

Loads the docs_installation_block template from file and returns a jinja2 jinja2.environment.Template for it.

Return type

Template

Loads the docs_links_block template from file and returns a jinja2 jinja2.environment.Template for it.

Return type

Template

get_readme_installation_block_no_pypi_template()[source]

Loads the readme_installation_block_no_pypi template from file and returns a jinja2 jinja2.environment.Template for it.

New in version 2020.12.1.

Return type

Template

get_readme_installation_block_template()[source]

Loads the readme_installation_block template from file and returns a jinja2 jinja2.environment.Template for it.

Return type

Template

installation_regex

Type:    Pattern

Regular expression to match the installation block placeholder.

Pattern

(.. start installation)(.*?)(.. end installation)

Flags

re.DOTALL

Type:    Pattern

Regular expression to match the links block placeholder.

Pattern

(.. start links)(.*?)(.. end links)

Flags

re.DOTALL

shields_regex

Type:    Pattern

Regular expression to match the shields block placeholder.

Pattern

(.. start shields)(.*?)(.. end shields)

Flags

re.DOTALL

short_desc_regex

Type:    Pattern

Regular expression to match the short description block placeholder.

Pattern

(.. start short[-_]desc)(.*?)(.. end short[-_]desc)

Flags

re.DOTALL