A collection of tools for commmon package scripts
Project description
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.
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.
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"] } )
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for jgt_tools-0.4.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 995497ce30fdef5a5fb794f17a91e6a901632ae801ce1e6b913c34ec70b1e9ce |
|
MD5 | f5dfc76ec856fb67f93b184d0f8f9f93 |
|
BLAKE2b-256 | aa22e2dd6f52f23e6000737a603da2d7f7b3295328a7a10db876b7681e4937b4 |