jgt-tools 0.3.1

A collection of tools for commmon package scripts

JGT Tools is a collection of package helpers for common CLI functions within a properly-formatted repository.

Quickstart

Just include jgt_tools in your package VirtualEnv, and you’ll have access to these CLI calls:

• env-setup - set up the development environment with all packages and pre-commit checks

• self-check - run self-checks/linters/etc. on your repository

• run-tests - run your in-repo test suite

• build-docs - build repo documentation locally

• build-and-push-docs - both build the docs, then publish to your gh-pages branch

• check-version - raise an error if package-relevant files have changed without a version bump

Details for each script can be found by calling with the --help flag.

Documentation Index

In order to get the full benefit from build-docs, it is encouraged to create an index file that pulls together all the documentation. This file needs to be in the root folder and should be called .jgt_tools.index. This will be moved into the working directory for Sphinx and be used when building the documentation. Additional information can be found on the Sphinx site.

Configuration

A number of the actions to be called can be customized in a [tool.jgt_tools] in your pyproject.toml file. Available values are:

• env_setup_commands - a list of commands to be run under the env-setup call

• self_check_commands - a list of commands to be run under the self-check call

• run_tests_commands - a list of commands to be run under the run-tests call

• build_docs_commands - a list of commands to be run under the build-docs call

For example:

[tool.jgt_tools]
env_setup_commands = [
    "poetry install",
    "poetry run pip install other_package",
    "./my_custom_setup_script.sh"
]
build_docs_commands = []

would run your specified commands for env-setup and skip the default api doc builder.

Note

NOTE: All commands provided in [tools.jgt_tools] will be run from project root. To ensure your commands run as expected, provide any paths in your custom commands relative from root.

build_docs_commands

Specifically for build_docs_commands, there are some variables that can be used to aid in documentation building, using Python-style curly-brace formatting:

BASE_DIR: Root library directory
PACKAGE_NAME: Folder name containing package
DOCS_WORKING_DIRECTORY: Temporary directory where docs are built (needed for Sphinx)
DOCS_OUTPUT_DIRECTORY: Final directory where docs are saved

For example:

[tool.jgt_tools]
build_docs_commands = [
    "poetry run sphinx-apidoc --output-dir {DOCS_WORKING_DIRECTORY} --no-toc --force --module-first {PACKAGE_NAME}
]

builds the Sphinx API docs for the current package and stores the output files in the temporary working directory.

check-version

In addition, the function to verify which files are relevant to check-version can be customized. By default, if any files in the diff against master are .py files, a version bump is expected, but the user can provide an alternate function to verify filenames.

The function should expect a list of strings representing file paths relative from project root (as provided by git diff master --name-only) and return a boolean representing if a version change should be ensured (i.e. True if version should be checked).

This can be registered as a plugin in your pyproject.toml file:

[tools.poetry.plugins."file_checkers"]
"version_trigger" = "my_module:my_function"

or in your setup.py file:

setup(
    ...
    entry_points={
        "version_trigger": ["version_trigger = my_module:my_fuction"]
    }
)