Package: jgt-tools
JGT Tools is a collection of package helpers
for common CLI functions
within a properly-formatted repository.QuickstartJust includejgt_toolsin 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 checksself-check- run self-checks/linters/etc. on your repositoryrun-tests- run your in-repo test suitebuild-docs- build repo documentation locallybuild-and-push-docs- both build the docs,
then publish to your gh-pages branchcheck-version- raise an error if package-relevant files have changed
without a version bumpDetails for each script can be found by calling with the--helpflag.TipIn 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.
Whenenv-setupis 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-testsTherun-testscommands will
pass through any additional parameters
provided on the command line.
For example,
by defaultrun-testsmaps to:poetry run python -m pytest -vvvRunningrun-tests-swould run:poetry run python -m pytest -vvv -sDocumentation IndexIn order to get the full benefit frombuild-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 theSphinx site.ConfigurationA number of the actions to be called
can be customized in a[tool.jgt_tools]in yourpyproject.tomlfile.
Available values are:env_setup_commands- a list of commands to be run
under theenv-setupcallself_check_commands- a list of commands to be run
under theself-checkcallrun_tests_commands- a list of commands to be run
under therun-testscallbuild_docs_commands- a list of commands to be run
under thebuild-docscallFor 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 forenv-setupand skip the default api doc builder.NoteNOTE: 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_commandsSpecifically forbuild_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 savedFor 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-versionIn addition,
the function to verify which files are relevant tocheck-versioncan be customized.
By default, if any files in the diff against master are.pyfiles,
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 bygit diff master--name-only)
and return a boolean representing if a version change should be ensured
(i.e.Trueif version should be checked).This can be registered as a plugin in yourpyproject.tomlfile:[tools.poetry.plugins."file_checkers"]
"version_trigger" = "my_module:my_function"or in yoursetup.pyfile:setup(
    ...
    entry_points={
        "version_trigger": ["version_trigger = my_module:my_fuction"]
    }
)