From a7391a6955c5ddc953556d231d4b0fe5e03c0a5c Mon Sep 17 00:00:00 2001
From: Nick Brown <nb745@cam.ac.uk>
Date: Tue, 4 Feb 2025 16:29:45 +0000
Subject: [PATCH 1/2] feat: Add libraries-tools top-level section & pages
---
.gitignore | 1 +
docs/libraries-tools/gcp-terraform/index.md | 31 ++++++++++++
docs/libraries-tools/git-ci-docker/index.md | 13 +++++
docs/libraries-tools/index.md | 7 +++
docs/libraries-tools/python/index.md | 53 +++++++++++++++++++++
mkdocs.yml | 8 ++++
6 files changed, 113 insertions(+)
create mode 100644 docs/libraries-tools/gcp-terraform/index.md
create mode 100644 docs/libraries-tools/git-ci-docker/index.md
create mode 100644 docs/libraries-tools/index.md
create mode 100644 docs/libraries-tools/python/index.md
diff --git a/.gitignore b/.gitignore
index 6f20fe31..d8825222 100644
--- a/.gitignore
+++ b/.gitignore
@@ -22,3 +22,4 @@ __pycache__/
# build documentation
public/
docs/plantuml-diagrams/out/
+.aider*
diff --git a/docs/libraries-tools/gcp-terraform/index.md b/docs/libraries-tools/gcp-terraform/index.md
new file mode 100644
index 00000000..e0133b61
--- /dev/null
+++ b/docs/libraries-tools/gcp-terraform/index.md
@@ -0,0 +1,31 @@
+# GCP & Terraform
+
+Our adopted & recommended tools & services for Google Cloud Platform (GCP) and Terraform.
+
+## GCP Tools & Services
+
+<!-- markdownlint-disable MD013 -->
+| Title | Summary | Our Docs |
+|-----------------------------------------------------------------|----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|
+| [Cloud Run](https://cloud.google.com/run) | Serverless container platform for stateless applications | [Reference](../../reference/cloud-platform/index.md), [Migration](../../explanations/gcp-cloud-run-app-module.md) |
+| [Cloud SQL](https://cloud.google.com/sql) | Fully managed relational database service | [Backups](../../reference/cloud-platform/backups.md) |
+| [Cloud Storage](https://cloud.google.com/storage) | Object storage service | [Reference](../../reference/cloud-platform/index.md) |
+| [Cloud Load Balancing](https://cloud.google.com/load-balancing) | Scalable load distribution service | [Architecture](../../reference/standard-architecture-diagrams.md) |
+| [Cloud DNS](https://cloud.google.com/dns) | Managed DNS service | [DNS Guide](../../reference/cloud-platform/dns.md) |
+| [Secret Manager](https://cloud.google.com/secret-manager) | Secure secret storage service | [CI Access](../../howtos/gke-gitlab-runners/access-secrets-in-ci-jobs-using-impersonation.md) |
+| [Cloud Monitoring](https://cloud.google.com/monitoring) | Infrastructure and application monitoring service | [Reference](../../reference/cloud-platform/index.md) |
+| [Cloud Logging](https://cloud.google.com/logging) | Centralized log management service | [Reference](../../reference/cloud-platform/index.md) |
+| [gcloud CLI](https://cloud.google.com/sdk/gcloud) | Command-line interface for GCP services | [System Setup](../../howtos/prepare-your-system.md) |
+<!-- markdownlint-enable MD013 -->
+
+## Terraform & Infrastructure Tools
+
+<!-- markdownlint-disable MD013 -->
+| Title | Summary | Our Docs |
+|------------------------------------------------------------------------------------------------|----------------------------------------------|--------------------------------------------------------------|
+| [Terraform](https://www.terraform.io/) | Infrastructure as Code tool | [Reference](../../reference/cloud-platform/index.md) |
+| [terraform-provider-google](https://registry.terraform.io/providers/hashicorp/google/latest) | Google Cloud Platform provider for Terraform | [Reference](../../reference/cloud-platform/index.md) |
+| [terraform-provider-aws](https://registry.terraform.io/providers/hashicorp/aws/latest) | Amazon Web Services provider for Terraform | [AWS Guide](../../explanations/aws.md) |
+| [terraform-provider-azurerm](https://registry.terraform.io/providers/hashicorp/azurerm/latest) | Microsoft Azure provider for Terraform | [Azure Guide](../../explanations/azure-and-entra-id-apps.md) |
+| [tflint](https://github.com/terraform-linters/tflint) | Terraform linter | [Reference](../../reference/cloud-platform/index.md) |
+<!-- markdownlint-enable MD013 -->
diff --git a/docs/libraries-tools/git-ci-docker/index.md b/docs/libraries-tools/git-ci-docker/index.md
new file mode 100644
index 00000000..dd9f0066
--- /dev/null
+++ b/docs/libraries-tools/git-ci-docker/index.md
@@ -0,0 +1,13 @@
+# Development Tools & Services
+
+Our adopted & recommended tools & services for Git, CI & Docker.
+
+<!-- markdownlint-disable MD013 -->
+| Title | Summary | Our Docs |
+|--------------------------------------------------|------------------------------------------------|----------------------------------------------------------|
+| [Docker](https://www.docker.com/) | Container platform | [System Setup](../../howtos/prepare-your-system.md) |
+| [GitLab CI/CD](https://docs.gitlab.com/ee/ci/) | Continuous Integration and Deployment platform | [Tutorial](../../tutorials/creating-a-python-package.md) |
+| [GitLab Runner](https://docs.gitlab.com/runner/) | CI/CD job execution agent | [GKE Guide](../../explanations/gke-gitlab-runners.md) |
+| [renovatebot](https://www.mend.io/renovate/) | Automated dependency updates | [Guide](../../explanations/renovatebot.md) |
+| [pre-commit](https://pre-commit.com/) | Git hook framework | [Setup](../../howtos/setup-pre-commit-hooks.md) |
+<!-- markdownlint-enable MD013 -->
diff --git a/docs/libraries-tools/index.md b/docs/libraries-tools/index.md
new file mode 100644
index 00000000..e5868512
--- /dev/null
+++ b/docs/libraries-tools/index.md
@@ -0,0 +1,7 @@
+# Libraries & Tools
+
+A collection of various libraries, snippets & tools which are:
+
+- Formative in our boilerplate projects and/or daily processes.
+- An in-house standard based on consensus over time.
+- Especially time-saving & useful!
diff --git a/docs/libraries-tools/python/index.md b/docs/libraries-tools/python/index.md
new file mode 100644
index 00000000..9bda1a13
--- /dev/null
+++ b/docs/libraries-tools/python/index.md
@@ -0,0 +1,53 @@
+# Python
+
+Our adopted & recommended Python libraries, snippets & tools.
+
+## Libraries
+
+<!-- markdownlint-disable MD013 -->
+| Title | Summary | Our Docs |
+|---------------------------------------------------------------------------------|---------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
+| [black](https://github.com/psf/black) | Code formatter that enforces a consistent style | [Setup](../../howtos/setup-pre-commit-hooks.md), [Tutorial](../../tutorials/creating-a-python-package.md) |
+| [coverage](https://coverage.readthedocs.io/) | Tool for measuring code coverage of Python programs | [Tutorial](../../tutorials/creating-a-python-package.md) |
+| [docopt](http://docopt.org/) | Command-line interface description language and parser | [Tutorial](../../tutorials/creating-a-python-package.md) |
+| [faker](https://faker.readthedocs.io/) | Library for generating fake data for testing | [Tutorial](../../tutorials/creating-a-python-package.md) |
+| [flake8](https://flake8.pycqa.org/) | Tool for style guide enforcement and linting | [Setup](../../howtos/setup-pre-commit-hooks.md), [Tutorial](../../tutorials/creating-a-python-package.md) |
+| [furo](https://pradyunsg.me/furo/) | Clean customizable Sphinx documentation theme | [Tutorial](../../tutorials/creating-a-python-package.md) |
+| [geddit](https://gitlab.developers.cam.ac.uk/uis/devops/lib/geddit) | UIS library for fetching data from URLs | [Tutorial](../../tutorials/creating-a-python-package.md) |
+| [isort](https://pycqa.github.io/isort/) | Library for sorting Python imports | [Setup](../../howtos/setup-pre-commit-hooks.md), [Tutorial](../../tutorials/creating-a-python-package.md) |
+| [jsonpath-ng](https://github.com/h2non/jsonpath-ng) | Library for extracting data using JSONPath expressions | [Tutorial](../../tutorials/creating-a-python-package.md) |
+| [mypy](https://mypy.readthedocs.io/) | Static type checker for Python | [Setup](../../howtos/setup-pre-commit-hooks.md), [Tutorial](../../tutorials/creating-a-python-package.md) |
+| [pre-commit](https://pre-commit.com/) | Framework for managing git pre-commit hooks | [Setup](../../howtos/setup-pre-commit-hooks.md), [Tutorial](../../tutorials/creating-a-python-package.md) |
+| [PyYAML](https://pyyaml.org/) | YAML parser and emitter for Python | [Tutorial](../../tutorials/creating-a-python-package.md) |
+| [pytest](https://docs.pytest.org/) | Testing framework | [Tutorial](../../tutorials/creating-a-python-package.md), [Boilerplate](../../explanations/webapp-boilerplate.md#testing) |
+| [pytest-cov](https://pytest-cov.readthedocs.io/) | Coverage plugin for pytest | [Tutorial](../../tutorials/creating-a-python-package.md) |
+| [pytest-mock](https://pytest-mock.readthedocs.io/) | Thin-wrapper around mock package for pytest | [Tutorial](../../tutorials/creating-a-python-package.md) |
+| [python-social-auth](https://python-social-auth.readthedocs.io/) | Authentication framework for Python web frameworks | [SSO Guide](../../howtos/configure-django-for-sso.md) |
+| [sphinx](https://www.sphinx-doc.org/) | Documentation generator | [Tutorial](../../tutorials/creating-a-python-package.md) |
+| [sphinx-autodoc-typehints](https://github.com/tox-dev/sphinx-autodoc-typehints) | Type hints support for Sphinx | [Tutorial](../../tutorials/creating-a-python-package.md) |
+| [structlog](https://www.structlog.org/) | Structured logging for Python | [Tutorial](../../tutorials/creating-a-python-package.md) |
+| [tox](https://tox.wiki/) | Test automation and virtual environment management tool | [Tutorial](../../tutorials/creating-a-python-package.md) |
+<!-- markdownlint-enable MD013 -->
+
+## Snippets
+
+<!-- markdownlint-disable MD013 -->
+| Type | Snippet | Summary |
+|------------|----------------------------------------------------------------------|-------------------------------------------|
+| decorator | [decorators](https://gitlab.developers.cam.ac.uk/-/snippets/340) | neat multiple decorators in a single line |
+| decorator | [threadsafe](https://gitlab.developers.cam.ac.uk/-/snippets/341) | make a method or property thread-safe |
+| datastruct | [dotdict](https://gitlab.developers.cam.ac.uk/-/snippets/343) | dot-accessible dict |
+| datastruct | [threadsafedict](https://gitlab.developers.cam.ac.uk/-/snippets/342) | exemplifies how to use Generic typing |
+<!-- markdownlint-enable MD013 -->
+
+## Tools
+
+<!-- markdownlint-disable MD013 -->
+| Title | Summary | Our Docs |
+|------------------------------------------|----------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
+| [copier](https://copier.readthedocs.io/) | Tool for rendering project templates | [Create](../../howtos/copier-create.md), [Update](../../howtos/copier-update.md), [Migrate](../../howtos/copier-migrate.md) |
+| [pip](https://pip.pypa.io/) | Package installer for Python | [System Setup](../../howtos/prepare-your-system.md) |
+| [pipx](https://pypa.github.io/pipx/) | Tool to install and run Python applications in isolated environments | [System Setup](../../howtos/prepare-your-system.md) |
+| [poetry](https://python-poetry.org/) | Python dependency management and packaging tool | [Tutorial](../../tutorials/creating-a-python-package.md), [Boilerplate](../../explanations/webapp-boilerplate.md#poetry) |
+| [poe](https://poethepoet.natn.io/) | Task runner that works well with poetry | [Tutorial](../../tutorials/creating-a-python-package.md), [Boilerplate](../../explanations/webapp-boilerplate.md#poe) |
+<!-- markdownlint-enable MD013 -->
diff --git a/mkdocs.yml b/mkdocs.yml
index 8c116994..5e88389a 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -274,6 +274,14 @@ nav:
- services/lecture-capture-preferences.md
- services/software-sales.md
- services/tls-certificates.md
+ - "Libraries & Tools":
+ - libraries-tools/index.md
+ - "Git, CI & Docker":
+ - libraries-tools/git-ci-docker/index.md
+ - "GCP & Terraform":
+ - libraries-tools/gcp-terraform/index.md
+ - "Python":
+ - libraries-tools/python/index.md
# Links for sufficiently with it people to submit changes.
repo_url: "https://gitlab.developers.cam.ac.uk/uis/devops/docs/guidebook/"
--
GitLab
From c3661ad1fdbb9bba324d1b3832f825183dace0ed Mon Sep 17 00:00:00 2001
From: Nick Brown <nb745@cam.ac.uk>
Date: Tue, 4 Feb 2025 17:03:06 +0000
Subject: [PATCH 2/2] chore: Add gitlab-ci-local to libraries-tools page
---
.gitignore | 1 -
docs/libraries-tools/git-ci-docker/index.md | 15 ++++++++-------
2 files changed, 8 insertions(+), 8 deletions(-)
diff --git a/.gitignore b/.gitignore
index d8825222..6f20fe31 100644
--- a/.gitignore
+++ b/.gitignore
@@ -22,4 +22,3 @@ __pycache__/
# build documentation
public/
docs/plantuml-diagrams/out/
-.aider*
diff --git a/docs/libraries-tools/git-ci-docker/index.md b/docs/libraries-tools/git-ci-docker/index.md
index dd9f0066..66a5f807 100644
--- a/docs/libraries-tools/git-ci-docker/index.md
+++ b/docs/libraries-tools/git-ci-docker/index.md
@@ -3,11 +3,12 @@
Our adopted & recommended tools & services for Git, CI & Docker.
<!-- markdownlint-disable MD013 -->
-| Title | Summary | Our Docs |
-|--------------------------------------------------|------------------------------------------------|----------------------------------------------------------|
-| [Docker](https://www.docker.com/) | Container platform | [System Setup](../../howtos/prepare-your-system.md) |
-| [GitLab CI/CD](https://docs.gitlab.com/ee/ci/) | Continuous Integration and Deployment platform | [Tutorial](../../tutorials/creating-a-python-package.md) |
-| [GitLab Runner](https://docs.gitlab.com/runner/) | CI/CD job execution agent | [GKE Guide](../../explanations/gke-gitlab-runners.md) |
-| [renovatebot](https://www.mend.io/renovate/) | Automated dependency updates | [Guide](../../explanations/renovatebot.md) |
-| [pre-commit](https://pre-commit.com/) | Git hook framework | [Setup](../../howtos/setup-pre-commit-hooks.md) |
+| Title | Summary | Our Docs |
+|---------------------------------------------------------------|------------------------------------------------|----------------------------------------------------------|
+| [Docker](https://www.docker.com/) | Container platform | [System Setup](../../howtos/prepare-your-system.md) |
+| [GitLab CI/CD](https://docs.gitlab.com/ee/ci/) | Continuous Integration and Deployment platform | [Tutorial](../../tutorials/creating-a-python-package.md) |
+| [GitLab CI Local](https://github.com/firecow/gitlab-ci-local) | Local debugging of GitLab pipelines. | |
+| [GitLab Runner](https://docs.gitlab.com/runner/) | CI/CD job execution agent | [GKE Guide](../../explanations/gke-gitlab-runners.md) |
+| [renovatebot](https://www.mend.io/renovate/) | Automated dependency updates | [Guide](../../explanations/renovatebot.md) |
+| [pre-commit](https://pre-commit.com/) | Git hook framework | [Setup](../../howtos/setup-pre-commit-hooks.md) |
<!-- markdownlint-enable MD013 -->
--
GitLab