JGT Tools

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.

Tip

In order to keep the environment as clean as possible, JGT Tools will only install the libraries needed to start the tool itself. However, several of the default commands rely on additional libraries. When env-setup is run for the first time, it will check to see if each set of commands is still default, and if so, install the libraries those commands need.

run-tests

The run-tests commands will pass through any additional parameters provided on the command line. For example, by default run-tests maps to:

poetry run python -m pytest -vvv

Running run-tests -s would run:

poetry run python -m pytest -vvv -s

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"]
    }
)

Beyond The Quick Start

Default Command Values

Default values for each are:

Default Command values

Configuration Key	Command
env_setup_commands	poetry run pip install –upgrade pip
env_setup_commands	poetry install
env_setup_commands	poetry run pre-commit install
self_check_commands	poetry run pre-commit run -a
run_tests_commands	poetry run python -m pytest -vvv
build_docs_commands	echo “Building {PACKAGE_NAME} docs”
build_docs_commands	find . -maxdepth 1 -name *.rst -exec cp {{}} {DOCS_WORKING_DIRECTORY} ;
build_docs_commands	poetry run sphinx-apidoc –output-dir {DOCS_WORKING_DIRECTORY} –no-toc –force –module-first {PACKAGE_NAME}
build_docs_commands	cp {BASE_DIR}/.jgt_tools.index {BASE_DIR}/{DOCS_WORKING_DIRECTORY}/index.rst
build_docs_commands	poetry run sphinx-build -c {DOCS_WORKING_DIRECTORY} -aEW {DOCS_WORKING_DIRECTORY} {DOCS_OUTPUT_DIRECTORY}

JGT Tools - What It Does

JGT Tools - How To Use It - Module Documentation

For users of this package, the nitty gritty coding and configuration details.

• jgt_tools package
  • Subpackages
    • jgt_tools.docs package
      • Submodules
      • jgt_tools.docs.build_docs module
      • jgt_tools.docs.sample_conf module
  • Submodules
  • jgt_tools.check_version module
    • check_default_branch()
    • check_version()
    • find_default_branch()
    • find_remote()
  • jgt_tools.env_setup module
    • env_setup()
    • main()
  • jgt_tools.run_tests module
    • main()
    • run_tests()
  • jgt_tools.self_check module
    • main()
    • self_check()
  • jgt_tools.utils module
    • execute_command_list()
    • get_pyproject_config()
    • load_configs()
    • owner_name_from()

Maintainer’s Documentation

• Maintainer’s Documentation
  • CLI scripts:

Indices and tables

• Index

• Module Index

• Search Page