From fd8c56c6bec9f6d980fb3752a772ab02b672ec9c Mon Sep 17 00:00:00 2001 From: Dan Helfman Date: Sun, 6 Aug 2023 23:44:31 -0700 Subject: [PATCH] Add brief source code reference documentation. --- NEWS | 2 ++ docs/how-to/develop-on-borgmatic.md | 3 +++ docs/reference/source-code.md | 29 +++++++++++++++++++++++++++++ 3 files changed, 34 insertions(+) create mode 100644 docs/reference/source-code.md diff --git a/NEWS b/NEWS index 59b81f1a..d93f2a71 100644 --- a/NEWS +++ b/NEWS @@ -2,6 +2,8 @@ * #727: Add a MariaDB database hook that uses native MariaDB commands instead of the deprecated MySQL ones. Be aware though that any existing backups made with the "mysql_databases:" hook are only restorable with a "mysql_databases:" configuration. + * Add a source code reference for getting oriented with the borgmatic code as a developer: + https://torsion.org/borgmatic/docs/reference/source-code/ 1.8.1 * #326: Add documentation for restoring a database to an alternate host: diff --git a/docs/how-to/develop-on-borgmatic.md b/docs/how-to/develop-on-borgmatic.md index c6a5adb6..761b9240 100644 --- a/docs/how-to/develop-on-borgmatic.md +++ b/docs/how-to/develop-on-borgmatic.md @@ -37,6 +37,9 @@ install (so without `--user`, as root), or even into a borgmatic is up to you, but generally an editable install makes development and testing easier. +To get oriented with the borgmatic source code, have a look at the [source +code reference](https://torsion.org/borgmatic/docs/reference/source-code/). + ## Automated tests diff --git a/docs/reference/source-code.md b/docs/reference/source-code.md new file mode 100644 index 00000000..90e4c10f --- /dev/null +++ b/docs/reference/source-code.md @@ -0,0 +1,29 @@ +--- +title: Source code reference +eleventyNavigation: + key: 🐍 Source code reference + parent: Reference guides + order: 3 +--- +## getting oriented + +If case you're interested in [developing on +borgmatic](https://torsion.org/borgmatic/docs/how-to/develop-on-borgmatic/), +here's an abridged primer on how its Python source code is organized to help +you get started. At the top level we have: + + * [borgmatic](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/borgmatic): The main borgmatic source module. Most of the code is here. + * [docs](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/docs): How-to and reference documentation, including the document you're reading now. + * [sample](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/sample): Example configurations for cron and systemd. + * [scripts](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/scripts): Dev-facing scripts for things like building documentation and running end-to-end tests. + * [tests](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/tests): Automated tests organized by: end-to-end, integration, and unit. + +Within the `borgmatic` directory you'll find: + + * [actions](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/borgmatic/actions): Mid-level code for running each borgmatic action (create, list, check, etc.). + * [borg](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/borgmatic/borg): Lower-level code that actually shells out to Borg for each action. + * [commands](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/borgmatic/commands): Looking to add a new flag or action? Start here. This contains borgmatic's entry point, argument parsing, and shell completion. + * [config](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/borgmatic/config): Code responsible for loading, normalizing, and validating borgmatic's configuration. + * [hooks](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/borgmatic/hooks): Looking to add a new database or monitoring integration? Start here. + +So, broadly speaking, the control flow goes: `commands` → `config` followed by `commands` → `actions` → `borg` and `hooks`.