Update the README.md files for Poetry

README.md

@@ -4,6 +4,14 @@ Extended documentation for the [Botan](https://botan.randombit.net/)
 cryptography library in the context of the BSI project "Pflege und
 Weiterentwicklung der Kryptobibliothek Botan".
 
+## Repository Anatomy
+
+This monorepo contains documents (in `/docs`) as well as auxiliary helper
+scripts (in `/tools`). Most documents come with a `Makefile` to build them as
+PDF, HTML or other formats. Some generators depend on the helper scripts in
+`/tools`. We use [Poetry](https://python-poetry.org/) to manage the dependencies
+local and external dependencies.
+
 ## How to build the Documentation
 
 The documents are written using
@@ -12,13 +20,25 @@ The documents are written using
 tooling and generation steps. See the document-specific readmes for further
 guidance.
 
-Install Sphinx and other Python requirements using pip:
+We use [Poetry](https://python-poetry.org/) to manage the (internal and
+external) python dependencies of the document generators. In contrast to `pip`
+Poetry manages dependencies in virtual python environments. Therefore, it
+transparently handles the environment setup for the document generators.
+
+To install poetry run:
+
+```bash
+sudo apt install python3-poetry
+```
+
+Now, install Sphinx and other Python requirements of individual documents using
+Poetry:
 
 ```bash
 # Go into the directory of the document you want to build, e.g.
-cd cryptodoc
+cd docs/cryptodoc
 # Install Sphinx and the respective Python dependencies
-pip install -r requirements.txt
+poetry install
 ```
 
 ### Create PDF
@@ -37,9 +57,9 @@ To build a PDF do the following:
 
 ```bash
 # Go into the directory of the document you want to build, e.g.
-cd cryptodoc
+cd docs/cryptodoc
 # Create the PDF
-make latexpdf
+poetry run make latexpdf
 ```
 
 The PDF will be in the `_build/latex/` subfolder.
@@ -50,9 +70,5 @@ The recommended editor for editing the documentation is [*Visual Studio
 Code*](https://code.visualstudio.com/). A minimal configuration for *Visual
 Studio Code* with recommended extensions is included in the repository.
 
-Some extensions need additional Python requirements. Install them using pip within
-the respective directory:
-
-```bash
-pip install -r requirements-dev.txt
-```
+Some extensions need additional Python requirements. They are installed
+automatically via Poetry.

docs/audit_report/README.md

@@ -6,18 +6,14 @@ This document is part of the BSI project "Pflege und Weiterentwicklung der Krypt
 
 This document has a custom build step to generate the audit report document from
 YAML files and information from the GitHub API. This is done with a generator
-that resides in `../../audit_generator` written in Python with a few dependencies.
-Make sure to install them additionally to the dependencies of this document:
+that resides in `../../tools/genaudit` written in Python with a few dependencies.
 
-```bash
-pip install -r ../../audit_generator/requirements.txt
-```
-
-Also, the path to the generator scripts must be in your `$PYTHONPATH` before
-invoking `make`:
+As with the other documents, local and external dependencies are managed using
+Poetry. To generate the document simply run:
 
 ```bash
-PYTHONPATH=../../audit_generator make latexpdf
+poetry install
+poetry run make latexpdf
 ```
 
 Note that the GitHub API has a rather tight rate limit on clients without a

tools/genaudit/README.md

@@ -61,13 +61,19 @@ Auditers from the YAML file are rendered in parenthesis along with potential
 approvers from GitHub in the final rendering. Use the auditer's GitHub handle!
 
 Eventually, the directory with all topic description YAML files is passed to
-`audit.py` to render them into rST documents to be consumed by Sphinx.
+the CLI to render them into rST documents to be consumed by Sphinx.
 
-## Usage of audit.py
+## Usage of the CLI
 
-Currently, the script has two modes: `render` and `unrefed`. It takes a
-configuration file (`config.yml`) and requires a number of parameters to be
-passed. Most notably, a GitHub access token (via `--token` or from the
+The CLI can be launched like this:
+
+```bash
+python3 -m genaudit.cli
+```
+
+Currently, the script has three modes: `render`, `unrefed` and `verify_merges`.
+It takes a configuration file (`config.yml`) and requires a number of parameters
+to be passed. Most notably, a GitHub access token (via `--token` or from the
 environment variable `$BASIC_GH_TOKEN`). All information pulled from GitHub by
 the generator is public; nevertheless requests that feature an access token are
 subject to relaxed API rate limits.
@@ -103,17 +109,17 @@ topics: topics_directory
 cache: /path/to/github/cache/directory  # (optional)
 ```
 
-### Rendering (`audit.py render`)
+### Rendering (`python3 -m genaudit.cli render`)
 
 This renders all topics into restructured text files to be consumed by a Sphinx
 documentation generator. Example:
 
 ```bash
 export BASIC_GH_TOKEN="<mytoken>" # should be placed in the environment in some reasonable way
-python audit.py render -o <output_dir> <config_dir>
+python3 -m genaudit.cli render -o <output_dir> <config_dir>
 ```
 
-### Finding unreferenced Patches (`audit.py unrefed`)
+### Finding unreferenced Patches (`python3 -m genaudit.cli unrefed`)
 
 This is useful to find patches that landed in the relevant audit interval
 (`audit_ref_from` through `audit_ref_to`) but are not referenced in any topic
@@ -124,10 +130,10 @@ Example:
 
 ```bash
 export BASIC_GH_TOKEN="<mytoken>" # should be placed in the environment in some reasonable way
-python audit.py unrefed --yaml <config_dir>
+python3 -m genaudit.cli unrefed --yaml <config_dir>
 ```
 
-### Verifying Pull Requests' Merge Commits (`audit.py verify_merges)
+### Verifying Pull Requests' Merge Commits (`python3 -m genaudit.cli`)
 
 For accountability reasons we keep track of the merge commits' hashes for each
 pull request that landed. This command allows validating that all referenced
@@ -138,14 +144,14 @@ Example:
 
 ```bash
 export BASIC_GH_TOKEN="<mytoken>" # should be placed in the environment in some reasonable way
-python audit.py verify_merges <config_dir>
+python3 -m genaudit.cli verify_merges <config_dir>
 ```
 
 To additionally gain YAML-formatted corrections for pull requests that don't
 feature any merge commit or that appear inconsistent with the local checkout, run:
 
 ```bash
-python audit.py verify_merges --yaml <config_dir>
+python3 -m genaudit.cli verify_merges --yaml <config_dir>
 ```
 
 ## Limitations