[PATCH v3 3/3] doc: Add documentation

[Adam Hassick <ahassick@iol.unh.edu>]

Adds a new directory for storing documentation related to scripts and
other utilities in the dpdk-ci repository. Adds a new document
describing the create series artifact script.

Signed-off-by: Adam Hassick <ahassick@iol.unh.edu>
---
 doc/create_series_artifact.rst | 103 +++++++++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)
 create mode 100644 doc/create_series_artifact.rst

diff --git a/doc/create_series_artifact.rst b/doc/create_series_artifact.rst
new file mode 100644
index 0000000..d3a60f9
--- /dev/null
+++ b/doc/create_series_artifact.rst
@@ -0,0 +1,103 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+   Copyright(c) 2024 University of New Hampshire
+
+Create Series Artifact Script
+=============================
+
+The create series artifact script is a small Python script for automatically applying patches and
+storing the resulting source tree in an archive.
+It gathers some information about the patches into a Java properties file for later use.
+This script is meant to be used in the context of a CI pipeline.
+
+
+Purpose and Context
+-------------------
+
+A CI pipeline needs to make branching decisions when running on a patch or series depending on the
+contents of the series or what tree it's being applied onto.
+Tests running in a pipeline should run in parallel in order to shorten the time to report results.
+This script helps to meet these needs by creating a portable archive containing the DPDK source
+tree with the patch or series applied, and some metadata about that patch or series.
+A CI pipeline and tests can use this information to make branching decisions based on the scope of
+the patch.
+Tests running in a CI pipeline can easily copy this archive and unpack it to obtain a clean
+workspace, and this can be done independently of other tests.
+At the Community Lab, the output archive from this script is stored as a Jenkins artifact.
+This is the origin of the term "artifact" in the context of this script.
+Jobs triggered downstream can then copy the artifact into their workspaces and extract them.
+This script may also serve as a reference process for applying patches that new testing labs can
+pull down and get started with.
+
+
+Dependencies
+------------
+
+The script requires the following packages to be installed in the environment:
+
+* pygit2
+* pyyaml
+* git-pw
+
+Additionally, the script depends on pw_maintainers_cli and patch-parser, which are included.
+More information about configuring the script to find these dependencies can be found in the
+configuration section.
+
+
+Configuration
+-------------
+
+A YAML file is used to store configuration options for this script.
+The path to one of these configuration files is a required argument of the script.
+
+It is responsible for storing the following information:
+
+* Patchwork server, project, and user token
+* URL to use when cloning the DPDK repository
+* User information for Git
+* Paths to dependent scripts and their configuration files
+
+When providing a server URL, make sure to include the API version in the url.
+For example: ``https://patches.dpdk.org/api/1.3/``
+
+An example configuration file is given in the config directory of this repository at
+``config/artifacts.yml``.
+
+If you intend to execute this script from a different working directory, other than the tools
+directory inside this repository, then you will need to change the paths in the example
+configuration.
+
+Note that if you do not provide a patchwork token in the configuration file, then the optional
+argument ``--pw-token`` on the command line becomes a required argument.
+More detail on the command line interface can be found in the next section.
+
+
+Running the Script
+------------------
+
+Once you have a configuration file set up, running the script is simple.
+
+The script expects two required arguments:
+
+* A path to a configuration file
+* An API URL to a Series object in Patchwork
+
+The following block is an example of how to run the script:
+
+.. code-block:: console
+
+   ./create_series_artifact.py ../config/artifacts.yml \
+       https://patches.dpdk.org/api/1.3/series/12345
+
+If you choose not to provide a patchwork token in the configuration file, then you must provide
+it on the command line as follows:
+
+.. code-block:: console
+
+   ./create_series_artifact.py --pw-token <your-pw-token-here> \
+       ../config/artifacts.yml https://patches.dpdk.org/api/1.3/series/12345``
+
+It is not required to delete the ``dpdk`` directory that the script creates, or any of the other
+output files created by the script.
+The properties and log file will be overwritten in the next execution.
+If the ``dpdk`` directory is still present, then the script will retrieve and check out to the
+remote head rather than clone the repository again.
-- 
2.43.0