docs(mdbook): we're up

adamperkowski · Jan 6, 2025 · ab15ecf · ab15ecf
1 parent e603590
commit ab15ecf
Show file tree

Hide file tree

Showing 15 changed files with 965 additions and 94 deletions.
diff --git a/.github/workflows/mdbook.yml b/.github/workflows/mdbook.yml
@@ -0,0 +1,47 @@
+name: mdBook
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - *
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v2
+        with:
+          mdbook-version: 'latest'
+
+      - run: mdbook build book
+
+      - name: Set output directory
+        run: |
+          OUTDIR=$(basename ${{ github.ref }})
+          echo "OUTDIR=$OUTDIR" >> $GITHUB_ENV
+
+      - name: Deploy stable
+        uses: peaceiris/actions-gh-pages@v4
+        if: startswith(github.ref, 'refs/tags/')
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./book/book
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./book/book
+          destination_dir: ./${{ env.OUTDIR }}
diff --git a/README.md b/README.md
@@ -41,56 +41,10 @@ check the [release notes](https://github.com/adamperkowski/nvrs/releases) and [c
 ## Installation
 <a href="https://repology.org/project/nvrs/versions"><img align="right" src="https://repology.org/badge/vertical-allrepos/nvrs.svg" alt="Packaging status"></a>
 
-<details>
-<summary>Arch Linux</summary>
-
-[nvrs](https://aur.archlinux.org/packages/nvrs) is available as a package in the [AUR](https://aur.archlinux.org).<br>
-you can install it with your preferred [AUR helper](https://wiki.archlinux.org/title/AUR_helpers), example:
-
-```sh
-paru -S nvrs
-```
-
-or manually:
-
-```sh
-git clone https://aur.archlinux.org/nvrs.git
-cd nvrs
-makepkg -si
-```
-
-</details>
-
-<details>
-<summary>Cargo</summary>
-
-[nvrs](https://crates.io/crates/nvrs) can be installed via [Cargo](https://doc.rust-lang.org/cargo) with:
-
-```sh
-cargo install nvrs --all-features
-```
-
-note that crates installed using `cargo install` require manual updating with `cargo install --force`.
-
-</details>
-
-<details>
-<summary>Manual</summary>
-
-1. download the latest binary from [GitHub's release page](https://github.com/adamperkowski/nvrs/releases/latest)
-2. allow execution
-```sh
-chmod +x nvrs
-```
-3. move the file to a directory in `$PATH` (using `/usr/bin` as an example)
-```sh
-sudo mv nvrs /usr/bin/nvrs
-```
-
-</details>
+see the [installation guide](https://nvrs.adamperkowski.dev/installation.html) for instructions on how to install nvrs.
 
 ## Usage
-nvrs relies on a configuration file. see [configuration](#configuration). 
+nvrs relies on a configuration file. see [configuration](https://nvrs.adamperkowski.dev/configuration.html). 
 
 <img align='center' src='https://vhs.charm.sh/vhs-7j0ZLSJUnq5W8xwqjK14W4.gif' alt='Packaging status'>
 
@@ -118,55 +72,11 @@ nvrs -t ALL
 
 for all available commands, options and flags, see `nvrs --help` and the [manual page](/man/nvrs.1).
 
-## Configuration
-nvrs relies on a configuration file ([example](/nvrs.toml)) containing basic settings, such as `oldver`, `newver` & `keyfile` paths, as well as [package entries](#package-entries). supported config paths:
-- `$XDG_CONFIG_HOME/nvrs.toml` (`~/.config/nvrs.toml` if the variable is not set)
-- `./nvrs.toml`
-- custom paths set with `nvrs --config`
-
-### `__config__` table
-this configures the behavior of nvrs. see the [example config](/nvrs.toml#L7-L10).
-
-available fields:
-
-| name      | description                                                     | type   | required |
-|-----------|-----------------------------------------------------------------|--------|----------|
-| `oldver`  | path to the `oldver` file                                       | string | ✔️       |
-| `newver`  | path to the `newver` file                                       | string | ✔️       |
-| `keyfile` | path to a keyfile (see [keyfile structure](#keyfile-structure)) | string | ❌       |
-
-### Package entries
-
-[example](/nvrs.toml#L12-L15)
-
-package entries are custom entries in the main config file. they contain values such as:
-
-| name          | description                                                               | type   | required | custom |
-|---------------|---------------------------------------------------------------------------|--------|----------|--------|
-| `source`      | see [sources](#sources)                                                   | string | ✔️       | ❌     |
-| source name   | the "target". eg. repo path for `github`                                  | string | ✔️       | ✔️     |
-| `host`        | domain name the source is hosted on                                       | string | ❌       | ❌     |
-| `prefix`      | the prefix used in releases / tags<br>example: `v` for tags like `v0.1.0` | string | ❌       | ❌     |
-| `use_max_tag` | use max git tag instead of the latest release                             | bool   | ❌       | ❌     |
-| `url`         | url to check for source type `regex`                                      | string | ❌       | ❌     |
-| `regex`       | regex to search url for source type `regex`                               | bool   | ❌       | ❌     |
-
-### Keyfile structure
-this file contains API keys for various [sources](#sources). example can be found [here](/n_keyfile.toml).
-
-```toml
-[keys]
-github = "your_secret_github_api_key_that_you_shouldnt_push_to_a_public_nor_a_private_remote_repo_because_there_will_definitely_be_serious_consequences_sooner_or_later_if_you_do_trust_me_just_dont"
-gitlab = "remember_to_replace_the_example_values_here_here_with_your_actual_keys_otherwise_it_wont_work_but_dont_push_keyfiles_to_remote_repos"
-```
-
-<sub align='center'>"<i>I think that example value is not long enough</i>" - orhun</sub>
-
 ## Documentation
-the nvrs library documentation can be found at [docs.rs/nvrs](https://docs.rs/nvrs/latest/nvrs)
+full documentation can be found at [nvrs.adamperkowski.dev](https://nvrs.adamperkowski.dev).
+nvrs library documentation can be found at [docs.rs/nvrs](https://docs.rs/nvrs/latest/nvrs)
 
 ## Contributing
-
 if you want to contribute to the project, please read the [Contributing Guidelines](/CONTRIBUTING.md) before doing so.
 
 if you find any parts of the code or the documentation unclear, or have any suggestions, feel free to [open an issue](https://github.com/adamperkowski/nvrs/issues/new/choose) or a [pull request](https://github.com/adamperkowski/nvrs/pull/new).

diff --git a/book/.gitignore b/book/.gitignore
@@ -0,0 +1 @@
+book
diff --git a/book/book.toml b/book/book.toml
@@ -0,0 +1,17 @@
+[book]
+authors = ["Adam Perkowski"]
+language = "en"
+multilingual = false
+src = "src"
+title = "nvrs"
+
+[output.html]
+cname = "nvrs.adamperkowski.dev"
+default-theme = "nvrs"
+preferred-dark-theme = "nvrs"
+git-repository-url = "https://github.com/adamperkowski/nvrs"
+edit-url-template = "https://github.com/adamperkowski/nvrs/edit/main/book/{path}"
+additional-css = ["./theme/custom.css"]
+
+[output.html.search]
+use-boolean-and = true
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
@@ -0,0 +1,10 @@
+# Summary
+
+- [nvrs](./nvrs.md)
+- [features](./features.md)
+- [installation](./installation.md)
+- [configuration](./configuration.md)
+  - [`__config__` table](./config-table.md)
+  - [package entries](./package-entries.md)
+  - [keyfile structure](./keyfile-structure.md)
+- [credits](./credits.md)
diff --git a/book/src/config-table.md b/book/src/config-table.md
@@ -0,0 +1,10 @@
+# `__config__` table
+this configures the behavior of nvrs. see the [example config](https://github.com/adamperkowski/nvrs/blob/main/nvrs.toml#L7-L10).
+
+available fields:
+
+| name      | description                                                          | type   | required |
+|-----------|----------------------------------------------------------------------|--------|----------|
+| `oldver`  | path to the `oldver` file                                            | string | ✔️       |
+| `newver`  | path to the `newver` file                                            | string | ✔️       |
+| `keyfile` | path to a keyfile (see [keyfile structure](/keyfile-structure.html)) | string | ❌       |
diff --git a/book/src/configuration.md b/book/src/configuration.md
@@ -0,0 +1,5 @@
+# configuration
+nvrs relies on a TOML configuration file ([example](https://github.com/adamperkowski/nvrs/blob/main/nvrs.toml)) containing basic settings, such as `oldver`, `newver` & `keyfile` paths, as well as [package entries](/package-entries.md). supported config paths:
+- `$XDG_CONFIG_HOME/nvrs.toml` (`~/.config/nvrs.toml` if the variable is not set)
+- `./nvrs.toml`
+- custom paths set with `nvrs --config`
diff --git a/book/src/credits.md b/book/src/credits.md
@@ -0,0 +1,3 @@
+# credits
+- [依云](https://github.com/lilydjwg) | the original [nvchecker](https://github.com/lilydjwg/nvchecker)
+- [orhun](https://github.com/orhun) | the idea
diff --git a/book/src/features.md b/book/src/features.md
@@ -0,0 +1,15 @@
+# features
+### [nvchecker](https://github.com/lilydjwg/nvchecker) compatibility
+check the [release notes](https://github.com/adamperkowski/nvrs/releases) and [configuration docs](/configuration.html) for compatibility updates and instructions
+
+### speed
+<img align='right' src='https://media1.tenor.com/m/mMWXOkCEndoAAAAC/ka-chow-lightning-mcqueen.gif' alt='ka-chow' width=80 height=45>
+
+| command       | time per **updated** package | details                                                |
+|---------------|------------------------------|--------------------------------------------------------|
+| `nvrs`        | ~ 0.03s                      | **API requests included**<br>depends on internet speed |
+| `nvrs --cmp`  | ~ 0.0008s                    | depends on disk speed                                  |
+| `nvrs --take` | ~ 0.001s                     | depends on disk speed                                  |
+
+### sources
+see the [project's readme](https://github.com/adamperkowski/nvrs?tab=readme-ov-file#sources) for a list of supported sources
diff --git a/book/src/installation.md b/book/src/installation.md
@@ -0,0 +1,38 @@
+# installation
+<a href="https://repology.org/project/nvrs/versions"><img align="right" src="https://repology.org/badge/vertical-allrepos/nvrs.svg" alt="Packaging status"></a>
+
+## Arch Linux
+[nvrs](https://aur.archlinux.org/packages/nvrs) is available as a package in the [AUR](https://aur.archlinux.org).<br>
+you can install it with your preferred [AUR helper](https://wiki.archlinux.org/title/AUR_helpers), example:
+
+```sh
+paru -S nvrs
+```
+
+or manually:
+
+```
+git clone https://aur.archlinux.org/nvrs.git
+cd nvrs
+makepkg -si
+```
+
+## Cargo
+[nvrs](https://crates.io/crates/nvrs) can be installed via [Cargo](https://doc.rust-lang.org/cargo) with:
+
+```sh
+cargo install nvrs --all-features
+```
+
+note that crates installed using `cargo install` require manual updating with `cargo install --force`.
+
+## Manual
+1. download the latest binary from [GitHub's release page](https://github.com/adamperkowski/nvrs/releases/latest)
+2. allow execution
+```sh
+chmod +x nvrs
+```
+3. move the file to a directory in `$PATH` (using `/usr/bin` as an example)
+```sh
+sudo mv nvrs /usr/bin/nvrs
+```
diff --git a/book/src/keyfile-structure.md b/book/src/keyfile-structure.md
@@ -0,0 +1,10 @@
+# keyfile structure
+this file contains API keys for various [sources](https://github.com/adamperkowski/nvrs?tab=readme-ov-file#sources). example can be found [here](https://github.com/adamperkowski/nvrs/blob/main/n_keyfile.toml).
+
+```toml
+[keys]
+github = "your_secret_github_api_key_that_you_shouldnt_push_to_a_public_nor_a_private_remote_repo_because_there_will_definitely_be_serious_consequences_sooner_or_later_if_you_do_trust_me_just_dont"
+gitlab = "remember_to_replace_the_example_values_here_here_with_your_actual_keys_otherwise_it_wont_work_but_dont_push_keyfiles_to_remote_repos"
+```
+
+<sub align='center'>"<i>I think that example value is not long enough</i>" - orhun</sub>
diff --git a/book/src/nvrs.md b/book/src/nvrs.md
@@ -0,0 +1,33 @@
+# nvrs
+[![Grind Compliant](https://img.shields.io/badge/Grind-Compliant-blue?style=for-the-badge&labelColor=%23a8127d&color=%23336795)](https://github.com/grindhousedev/grindlines)
+
+fast new version checker for software releases
+
+documentation for bleeding-edge main can be found at [https://nvrs.adamperkowski.dev/main](https://nvrs.adamperkowski.dev/main)
+
+keep in mind that this website is still a WIP
+
+## copyright
+```
+MIT License
+
+Copyright (c) 2025 Adam Perkowski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
diff --git a/book/src/package-entries.md b/book/src/package-entries.md
@@ -0,0 +1,14 @@
+# package entries
+[example](https://github.com/adamperkowski/nvrs/blob/main/nvrs.toml#L12-L15)
+
+package entries are custom entries in the main config file. they contain values such as:
+
+| name          | description                                                                     | type   | required | custom |
+|---------------|---------------------------------------------------------------------------------|--------|----------|--------|
+| `source`      | see [sources](https://github.com/adamperkowski/nvrs?tab=readme-ov-file#sources) | string | ✔️       | ❌     |
+| source name   | the "target". eg. repo path for `github`                                        | string | ✔️       | ✔️     |
+| `host`        | domain name the source is hosted on                                             | string | ❌       | ❌     |
+| `prefix`      | the prefix used in releases / tags<br>example: `v` for tags like `v0.1.0`       | string | ❌       | ❌     |
+| `use_max_tag` | use max git tag instead of the latest release                                   | bool   | ❌       | ❌     |
+| `url`         | url to check for source type `regex`                                            | string | ❌       | ❌     |
+| `regex`       | regex to search url for source type `regex`                                     | bool   | ❌       | ❌     |