Add a manual page for the tox-stages utility

This manual page will be included in an upstream release soon.

2 files changed, 160 insertions, 0 deletions

diff --git a/debian/tox-stages.1 b/debian/tox-stages.1
new file mode 100644
index 0000000..5b299b3
--- /dev/null
+++ b/debian/tox-stages.1
@@ -0,0 +1,159 @@
+.\" Copyright (c) Peter Pentchev
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd February 8, 2023
+.Dt tox-stages 1
+.Os
+.Sh NAME
+.Nm tox-stages
+.Nd run Tox tests in groups, stopping on errors
+.Sh SYNOPSIS
+.Nm
+.Op Fl f Ar filename
+.Cm available
+.Nm
+.Op Fl f Ar filename
+.Cm run
+.Op Ar stage-spec...
+.Nm
+.Fl -help
+.Sh DESCRIPTION
+The
+.Nm
+tool runs Tox with the specified groups of test environments, stopping if
+any of the tests in a group should fail.
+This allows quick static check tools like e.g.
+.Cm ruff
+to stop the testing process early, and also allows scenarios like running
+all the static check tools before the package's unit or functional
+tests to avoid unnecessary failures on simple errors.
+.Pp
+If run with the
+.Cm available
+subcommand, the
+.Nm
+tool will check whether the Python environment that it is running from has
+a suitable version of Tox installed.
+If this is so,
+.Nm
+will exit with a status code of 0 without actually running Tox.
+If a suitable version of Tox is not installed,
+.Nm
+will exit with a non-zero exit code.
+.Pp
+If run with the
+.Cm run
+subcommand,
+.Nm
+will parse the
+.Pa tox.ini
+file (or the file specified by the
+.Fl f
+command-line option), read the definitions of the Tox test environments,
+group them according to the specified stages, and run the tests in each group
+in parallel.
+If the tests in one group fail, the ones in the rest of the groups are not
+executed at all.
+.Pp
+Note that a tag specified for a stage will only match Tox environments that
+have that exact tag name in their
+.Va tags
+list, but an environment name will be matched as a substring; thus,
+.Ar @check
+will only match the
+.Dq check
+tag, but not
+.Dq check-manual ,
+while
+.Ar ruff
+will match both
+.Dq ruff
+and
+.Dq ruff-all .
+.Pp
+If the
+.Cm run
+subcommand is invoked without any parameters, the
+.Nm
+tool will read the
+.Pa pyproject.toml
+file in the same directory as the
+.Pa tox.ini
+file being processed, and will look for a
+.Va tool.test-stages.stages
+list of strings to use.
+.Sh ENVIRONMENT
+The operation of the
+.Nm
+utility is not directly influenced by any environment variables.
+.Sh FILES
+If no stage specifications are given to the
+.Cm run
+subcommand, the
+.Pa pyproject.toml
+file is read and its
+.Va tool.test-stages.stages
+variable (expected to be a list of strings) is used instead.
+.Sh EXAMPLES
+Run the very quick checks in any test environments with names that
+include the string
+.Dq ruff ,
+then run all the environments that specify the
+.Dq check
+tag exactly, and then run the environments that specify the
+.Dq tests
+tag:
+.Pp
+.Dl tox-stages run ruff @check @tests
+.Pp
+Do the same, but exclude the ruff-like environments that specify the
+.Dq manual
+tag, and also run the environments that specify the
+.Dq ci
+tag in the last stage:
+.Pp
+.Dl tox-stages run 'ruff and not @manual' @check '@tests or @ci'
+.Pp
+.Sh DIAGNOSTICS
+.Ex -std
+.Sh SEE ALSO
+.Xr tox 1
+.Pp
+A description of the stage specification mini-language:
+https://gitlab.com/ppentchev/parse-stages
+.Sh STANDARDS
+No standards were harmed during the production of the
+.Nm
+utility.
+.Sh HISTORY
+The
+.Nm
+utility was written by Peter Pentchev in 2023.
+.Sh AUTHORS
+.An Peter Pentchev
+.Aq roam@ringlet.net
+.Sh BUGS
+No, thank you :)
+But if you should actually find any, please report them
+to the author.
diff --git a/debian/tox-stages.manpages b/debian/tox-stages.manpages
new file mode 100644
index 0000000..19a9822
--- /dev/null
+++ b/debian/tox-stages.manpages
@@ -0,0 +1 @@
+debian/tox-stages.1