`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, 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_docs_links_block(username, repo_name)[source]¶

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

get_docs_links_block_template()[source]¶

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`

links_regex¶

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`

repo_helper.blocks¶

`repo_helper.blocks`¶