diff --git a/README.md b/README.md index 4851bc53..8d2cfdee 100644 --- a/README.md +++ b/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. diff --git a/docs/audit_report/README.md b/docs/audit_report/README.md index 6b4244c0..a5ad6947 100644 --- a/docs/audit_report/README.md +++ b/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 diff --git a/tools/genaudit/README.md b/tools/genaudit/README.md index 2e25daf7..2aedb39d 100644 --- a/tools/genaudit/README.md +++ b/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="" # should be placed in the environment in some reasonable way -python audit.py render -o +python3 -m genaudit.cli render -o ``` -### 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="" # should be placed in the environment in some reasonable way -python audit.py unrefed --yaml +python3 -m genaudit.cli unrefed --yaml ``` -### 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="" # should be placed in the environment in some reasonable way -python audit.py verify_merges +python3 -m genaudit.cli verify_merges ``` 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 +python3 -m genaudit.cli verify_merges --yaml ``` ## Limitations