Commit
Message
Changed Files (4)
-
modified CHANGELOG.md
diff --git a/CHANGELOG.md b/CHANGELOG.md index ac8f202..6e4bc61 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,10 @@ - *(templates,cli)* Extract <header> into base.html; dump-theme only writes enabled formats - Orchestrator functions are now split in more functions +### 📚 Documentation + +- Add some more docs to README/crate docs to reflect new config options + ### ⚡ Performance - Don't read artifacts 2 times (1 to generate hash, the other to copy to final resting place -
modified README.md
diff --git a/README.md b/README.md index f3b91b4..d5ee6c1 100644 --- a/README.md +++ b/README.md @@ -63,6 +63,20 @@ You can clone the [repository](https://git.sr.ht/~ololduck/abbaye) and build the ## Usage Run `abbaye init` in your project's directory to create a `abbaye.toml` configuration file. You can then customize the configuration to your liking. + +## CLI commands + +| Command | Description | +|---------|-------------| +| `init` | Create a new `abbaye.toml` file. | +| `build` | Build the site. Use `--repository-only` to skip version pages and only rebuild the git UI. | +| `build-all` | Build the site for every git tag, from lowest to highest semver. Checks out each tag in order, builds, then restores HEAD. | +| `dump-theme` | Dump the default theme templates to `.abbaye/theme/` (only templates for formats enabled in `[site].formats`). | +| `dump-schema` | Print a JSON Schema for `abbaye.toml` to stdout (redirect to `abbaye.schema.json` for IDE autocompletion). | +| `self-update` | Check for and install the latest release. Add `--check` to only check without downloading. | + +## Configuration + Here's an example configuration file to get you started: ```toml @@ -70,6 +84,16 @@ Here's an example configuration file to get you started: name = "Abbaye" # required for Atom feed generation (canonical URLs are used for feed items) base_url = "http://vit.am/~ololduck/abbaye/" +# URL of the project's repository (shown on release pages) +repo_url = "https://git.sr.ht/~ololduck/abbaye" +# Output formats: "html", "gemtext", or both (default: ["html"]) +formats = ["html", "gemtext"] +# Fediverse handle for social meta tags +fediverse_creator = "@ololduck@vit.am" + +[site.opengraph] +image = "latest/logo.svg" +image_alt = "Abbaye logo" [version_extractor] type = "git" # extract version from git tags @@ -80,6 +104,9 @@ tag_prefix = "v" [[builders]] # builds the project using cargo build --release type = "cargo" targets = ["x86_64-unknown-linux-gnu", "x86_64-unknown-linux-musl"] +category = "Binaries" # groups artifacts under this heading +name = "Pre-built binaries" # optional display name on the release page +comment = "Built for Linux x86_64 (glibc and musl)." [[builders]] # generates documentation using cargo doc type = "cargo_doc" @@ -88,6 +115,7 @@ no_deps = true # Don't include dependencies in the documentation [[builders]] # creates a compressed tarball of the source code (can be of anything, really) type = "archive" +category = "Source" [[builders]] # Just an example dumb script to showcase the `script` builder type @@ -98,6 +126,21 @@ script = [ outputs = [".version"] ``` +Builders run **concurrently** by default. To enforce ordering, assign an `id` +and reference it in `depends_on`: + +```toml +[[builders]] +id = "compile" +type = "cargo" + +[[builders]] +depends_on = ["compile"] +type = "script" +script = ["strip target/release/mybin"] +outputs = ["target/release/mybin"] +``` + Then run `abbaye build` to build the site. The site will be generated in the `public/` directory by default. Now you can copy the contents of `public/` to your web server to deploy the site. For instance, with rsync: `rsync --progress -avz --links --perms --update public/ ololduck@vit.am:public_html/abbaye/` @@ -119,6 +162,10 @@ default_branch = "main" max_commits = 200 repo_path = "." clone_url = "{{ site.base_url }}/repository.git" +# Glob patterns for refs to EXCLUDE from the UI (optional). +exclude = ["gh-pages", "tmp/*"] +# Glob patterns for refs to INCLUDE (optional, acts as an allowlist). +include = ["main", "v*"] ``` When the git UI is enabled, pages permitting browsing the tree of the repository are available, _but only for the branches tips and the tags_, as to not generate too much content. It already is quite a lot of content to generate for a simple repository UI (about 10MBs for Abbaye's repository at the time of writing). @@ -127,7 +174,8 @@ When the git UI is enabled, pages permitting browsing the tree of the repository You can dump the default theme/templates to your local filesystem with `abbaye dump-theme`. -This will create a `.abbaye/theme/` directory in your current directory with the default templates, which you can then ✨customize✨. +This will create a `.abbaye/theme/` directory in your current directory with the default templates +(only for the output formats enabled in `[site].formats`), which you can then ✨customize✨. If you don't want to customize every template, simply delete the ones you don't want to change. @@ -138,12 +186,12 @@ In `.abbaye/theme/static/`, you will find the CSS sheet used by the default them - [x] Add support for theming - [ ] Add support for more site variables, such as the site title, description, and author, or even a custom footer and stuff. - I added OpenGraph support, does that count? -- [x] Add support for a `self-update`-like command to update the abbaye binary to the latest version. The mechanisms put in place for this goal should be usable to any user of `abbaye`. +- [x] Add support for a `self-update`-like command to update the abbaye binary to the latest version. ## Contributing Contributions are welcome! As i am mainly a rust developer, i am open to any contributions that improve the project, especially to support more artifacts builders/types. -Just clone the repository and {send me an email,contact me on {IRC (ololduck@irc.libera.chat),the Fediverse (@ololduck@fosstodon.org)}} with {a link to your fork,a git patch,compliments and adoration}. +Just clone the repository and {send me an email,contact me on {IRC (ololduck@irc.libera.chat),the Fediverse (@ololduck@vit.am)} with {a link to your fork,a git patch,compliments and adoration}. License: AGPL-3.0-or-later -
modified mise.toml
diff --git a/mise.toml b/mise.toml index 80891b6..0300966 100644 --- a/mise.toml +++ b/mise.toml @@ -93,6 +93,7 @@ arg "<new_version>" help="New version to release" confirm = "Are you sure you want to release?" description = "release the project" run = [ + 'git rev-parse --abbrev-ref HEAD | grep -q "^main$" || { echo "Not on main branch, aborting."; exit 1; }', 'sed -i "/^\[package\]/,/^\[/{s/^version = \".*\"/version = \"${usage_new_version}\"/}" Cargo.toml && git add Cargo.toml', "cargo generate-lockfile && git add Cargo.lock", 'git commit -am "chore: release v${usage_new_version}"', -
modified src/main.rs
diff --git a/src/main.rs b/src/main.rs index af4e4c2..fbd9d8e 100644 --- a/src/main.rs +++ b/src/main.rs @@ -63,6 +63,20 @@ //! ## Usage //! //! Run `abbaye init` in your project's directory to create a `abbaye.toml` configuration file. You can then customize the configuration to your liking. +//! +//! ## CLI commands +//! +//! | Command | Description | +//! |---------|-------------| +//! | `init` | Create a new `abbaye.toml` file. | +//! | `build` | Build the site. Use `--repository-only` to skip version pages and only rebuild the git UI. | +//! | `build-all` | Build the site for every git tag, from lowest to highest semver. Checks out each tag in order, builds, then restores HEAD. | +//! | `dump-theme` | Dump the default theme templates to `.abbaye/theme/` (only templates for formats enabled in `[site].formats`). | +//! | `dump-schema` | Print a JSON Schema for `abbaye.toml` to stdout (redirect to `abbaye.schema.json` for IDE autocompletion). | +//! | `self-update` | Check for and install the latest release. Add `--check` to only check without downloading. | +//! +//! ## Configuration +//! //! Here's an example configuration file to get you started: //! //! ```toml @@ -70,6 +84,16 @@ //! name = "Abbaye" //! # required for Atom feed generation (canonical URLs are used for feed items) //! base_url = "http://vit.am/~ololduck/abbaye/" +//! # URL of the project's repository (shown on release pages) +//! repo_url = "https://git.sr.ht/~ololduck/abbaye" +//! # Output formats: "html", "gemtext", or both (default: ["html"]) +//! formats = ["html", "gemtext"] +//! # Fediverse handle for social meta tags +//! fediverse_creator = "@ololduck@vit.am" +//! +//! [site.opengraph] +//! image = "latest/logo.svg" +//! image_alt = "Abbaye logo" //! //! [version_extractor] //! type = "git" # extract version from git tags @@ -80,6 +104,9 @@ //! [[builders]] # builds the project using cargo build --release //! type = "cargo" //! targets = ["x86_64-unknown-linux-gnu", "x86_64-unknown-linux-musl"] +//! category = "Binaries" # groups artifacts under this heading +//! name = "Pre-built binaries" # optional display name on the release page +//! comment = "Built for Linux x86_64 (glibc and musl)." //! //! [[builders]] # generates documentation using cargo doc //! type = "cargo_doc" @@ -88,6 +115,7 @@ //! [[builders]] //! # creates a compressed tarball of the source code (can be of anything, really) //! type = "archive" +//! category = "Source" //! //! [[builders]] //! # Just an example dumb script to showcase the `script` builder type @@ -98,6 +126,21 @@ //! outputs = [".version"] //! ``` //! +//! Builders run **concurrently** by default. To enforce ordering, assign an `id` +//! and reference it in `depends_on`: +//! +//! ```toml +//! [[builders]] +//! id = "compile" +//! type = "cargo" +//! +//! [[builders]] +//! depends_on = ["compile"] +//! type = "script" +//! script = ["strip target/release/mybin"] +//! outputs = ["target/release/mybin"] +//! ``` +//! //! Then run `abbaye build` to build the site. The site will be generated in the `public/` directory by default. //! Now you can copy the contents of `public/` to your web server to deploy the site. For instance, with rsync: //! `rsync --progress -avz --links --perms --update public/ ololduck@vit.am:public_html/abbaye/` @@ -119,6 +162,10 @@ //! max_commits = 200 //! repo_path = "." //! clone_url = "{{ site.base_url }}/repository.git" +//! # Glob patterns for refs to EXCLUDE from the UI (optional). +//! exclude = ["gh-pages", "tmp/*"] +//! # Glob patterns for refs to INCLUDE (optional, acts as an allowlist). +//! include = ["main", "v*"] //! ``` //! //! When the git UI is enabled, pages permitting browsing the tree of the repository are available, _but only for the branches tips and the tags_, as to not generate too much content. It already is quite a lot of content to generate for a simple repository UI (about 10MBs for Abbaye's repository at the time of writing). @@ -127,7 +174,8 @@ //! //! You can dump the default theme/templates to your local filesystem with `abbaye dump-theme`. //! -//! This will create a `.abbaye/theme/` directory in your current directory with the default templates, which you can then ✨customize✨. +//! This will create a `.abbaye/theme/` directory in your current directory with the default templates +//! (only for the output formats enabled in `[site].formats`), which you can then ✨customize✨. //! //! If you don't want to customize every template, simply delete the ones you don't want to change. //! @@ -138,13 +186,13 @@ //! - [x] Add support for theming //! - [ ] Add support for more site variables, such as the site title, description, and author, or even a custom footer and stuff. //! - I added OpenGraph support, does that count? -//! - [x] Add support for a `self-update`-like command to update the abbaye binary to the latest version. The mechanisms put in place for this goal should be usable to any user of `abbaye`. +//! - [x] Add support for a `self-update`-like command to update the abbaye binary to the latest version. //! //! ## Contributing //! //! Contributions are welcome! As i am mainly a rust developer, i am open to any contributions that improve the project, especially to support more artifacts builders/types. //! -//! Just clone the repository and {send me an email,contact me on {IRC (ololduck@irc.libera.chat),the Fediverse (@ololduck@fosstodon.org)}} with {a link to your fork,a git patch,compliments and adoration}. +//! Just clone the repository and {send me an email,contact me on {IRC (ololduck@irc.libera.chat),the Fediverse (@ololduck@vit.am)} with {a link to your fork,a git patch,compliments and adoration}. use std::path::PathBuf;