diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000..2ebcc96 --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,37 @@ +name: Generate Docs + +on: + push: + paths: + - docs/** + - .github/workflows/docs.yaml + branches: + - main + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Setup Hugo + uses: peaceiris/actions-hugo@v2 + with: + hugo-version: "0.147.7" + extended: true + + - name: Setup Node + uses: actions/setup-node@v2 + with: + node-version: "16.x" + + - run: | + cd docs + npm i + npm run build + + - name: Deploy + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/public + publish_branch: docs diff --git a/README.md b/README.md index 460f48d..efa511f 100644 --- a/README.md +++ b/README.md @@ -22,13 +22,13 @@ If you've heard of Overseer, Ombi, or Jellyseer; this is in the similar vein, NOTE: You can run both commands at once with `docker-compose up --build`. + +1. Verify that the service is working. + + Open your web browser and type `http://localhost:1313` in your navigation + bar, This opens a local instance of the docsy-example homepage. You can now + make changes to the docsy example and those changes will immediately show up + in your browser after you save. + +### Cleanup + +To stop Docker Compose, on your terminal window, press **Ctrl + C**. + +To remove the produced images run: + +```bash +docker-compose rm +``` + +For more information see the [Docker Compose documentation][]. + +## Using a local Docsy clone + +Make sure your installed go version is `1.18` or higher. + +Clone the latest version of the docsy theme into the parent folder of your +project. The newly created repo should now reside in a sibling folder of your +site's root folder. + +```shell +cd root-of-your-site +git clone --branch v0.12.0 https://github.com/google/docsy.git ../docsy +``` + +Now run: + +```shell +HUGO_MODULE_WORKSPACE=docsy.work hugo server --ignoreVendorPaths "**" +``` + +or, when using npm, prepend `local` to the script you want to invoke, e.g.: + +```shell +npm run local serve +``` + +By using the `HUGO_MODULE_WORKSPACE` directive (either directly or via prefix +`local` when using npm), the server now watches all files and directories inside +the sibling directory `../docsy` , too. Any changes inside the local `docsy` +theme clone are now immediately picked up (hot reload), you can instantly see +the effect of your local edits. + +In the command above, we used the environment variable `HUGO_MODULE_WORKSPACE` +to tell hugo about the local workspace file `docsy.work`. Alternatively, you can +declare the workspace file inside your settings file `hugo.toml`: + +```toml +[module] + workspace = "docsy.work" +``` + +Your project's `hugo.toml` file already contains these lines, the directive for +workspace assignment is commented out, however. Remove the two trailing comment +characters '//' so that this line takes effect. + +## Troubleshooting + +As you run the website locally, you may run into the following error: + +```console +$ hugo server +WARN 2023/06/27 16:59:06 Module "project" is not compatible with this Hugo version; run "hugo mod graph" for more information. +Start building sites … +hugo v0.101.0-466fa43c16709b4483689930a4f9ac8add5c9f66+extended windows/amd64 BuildDate=2022-06-16T07:09:16Z VendorInfo=gohugoio +Error: Error building site: "C:\Users\foo\path\to\docsy-example\content\en\_index.md:5:1": failed to extract shortcode: template for shortcode "blocks/cover" not found +Built in 27 ms +``` + +This error occurs if you are running an outdated version of Hugo. As of docsy +theme version `v0.12.0`, hugo version `0.146.0` or higher is required. See this +[section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-hugo) +of the user guide for instructions on how to install Hugo. + +Or you may be confronted with the following error: + +```console +$ hugo server + +INFO 2021/01/21 21:07:55 Using config file: +Building sites … INFO 2021/01/21 21:07:55 syncing static files to / +Built in 288 ms +Error: Error building site: TOCSS: failed to transform "scss/main.scss" (text/x-scss): resource "scss/scss/main.scss_9fadf33d895a46083cdd64396b57ef68" not found in file cache +``` + +This error occurs if you have not installed the extended version of Hugo. See +this +[section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-hugo) +of the user guide for instructions on how to install Hugo. + +Or you may encounter the following error: + +```console +$ hugo server + +Error: failed to download modules: binary with name "go" not found +``` + +This error occurs if the `go` programming language is not available on your +system. See this +[section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-go-language) +of the user guide for instructions on how to install `go`. + +[alternate dashboard]: https://app.netlify.com/sites/goldydocs/deploys +[deploys]: https://app.netlify.com/sites/docsy-example/deploys +[Docsy user guide]: https://docsy.dev/docs +[Docsy]: https://github.com/google/docsy +[example.docsy.dev]: https://example.docsy.dev +[Hugo theme module]: + https://gohugo.io/hugo-modules/use-modules/#use-a-module-for-a-theme +[Netlify]: https://netlify.com +[Docker Compose documentation]: https://docs.docker.com/compose/gettingstarted/ diff --git a/docs/assets/scss/_variables_project.scss b/docs/assets/scss/_variables_project.scss new file mode 100644 index 0000000..2569027 --- /dev/null +++ b/docs/assets/scss/_variables_project.scss @@ -0,0 +1,6 @@ +/* + +Add styles or override variables from the theme here. + +*/ + diff --git a/docs/config.yaml b/docs/config.yaml new file mode 100644 index 0000000..9070e38 --- /dev/null +++ b/docs/config.yaml @@ -0,0 +1,15 @@ +# THIS IS A TEST CONFIG ONLY! +# FOR THE CONFIGURATION OF YOUR SITE USE hugo.yaml. +# +# As of Docsy 0.7.0, Hugo 0.110.0 or later must be used. +# +# The sole purpose of this config file is to detect Hugo-module builds that use +# an older version of Hugo. +# +# DO NOT add any config parameters to this file. You can safely delete this file +# if your project is using the required Hugo version. + +module: + hugoVersion: + extended: true + min: 0.110.0 diff --git a/docs/content/_index.md b/docs/content/_index.md new file mode 100644 index 0000000..099fddd --- /dev/null +++ b/docs/content/_index.md @@ -0,0 +1,19 @@ +--- +title: AudioBookRequest +--- + +{{< blocks/cover title="Welcome to AudioBookRequest!" image_anchor="top" height="full" >}} + Get +started + +View Code + +

Audiobook request management/wishlist for Plex/Audiobookshelf/Jellyfin

+{{< blocks/link-down color="info" >}} +{{< /blocks/cover >}} + +{{% blocks/lead color="primary" %}} Your tool for handling audiobook requests on +a Plex/Audiobookshelf/Jellyfin instance. + +If you've heard of Overseer, Ombi, or Jellyseer; this is in the similar vein, +but for audiobooks. {{% /blocks/lead %}} diff --git a/docs/content/community/_index.md b/docs/content/community/_index.md new file mode 100644 index 0000000..8d226b5 --- /dev/null +++ b/docs/content/community/_index.md @@ -0,0 +1,5 @@ +--- +title: Community +menu: {main: {weight: 40}} +# Add blocks of content here to add more sections to the community page +--- diff --git a/docs/content/docs/_index.md b/docs/content/docs/_index.md new file mode 100644 index 0000000..af68d93 --- /dev/null +++ b/docs/content/docs/_index.md @@ -0,0 +1,41 @@ +--- +title: Overview +description: Welcome to the documentation for AudioBookRequest. +linkTitle: Overview +menu: { main: { weight: 20 } } +--- + +## What is it? + +AudioBookRequest is a tool that can be used in combination with media servers +like plex/audiobookserver/jellyfin/etc. to easily set up a pipeline for creating +a wishlist of audiobooks you want to listen to. + +## Why do I want it? + +Help your user know if your project will help them. Useful information can +include: + +- **What is it good for?**: If you have multiple people using your ABS instance + and you don't want them to always have to message you for new books or you + don't want to give them access to something like Readarr/Prowlarr, you can use + AudioBookRequest to allow them to easily request any books they want to listen + to and have it notify and/or automatically start any required downloads. + +- **What is it not good for?**: AudioBookRequest is **not** a full replacement + for Readarr, nor is that the plan. Readarr does a lot of things, but it is + also currently in a very messy state development-wise. ABR does not currently + keep track of your library, while automatically downloading new releases and + trying to upgrade the quality of already existing audiobooks. These are + features that are less relevant with audiobooks. + +- **What is it _not yet_ good for?**: AudioBookRequest is currently unable to + move any downloads, add metadata to files, or rename files according to some + structure. + +## Where should I go next? + +Head on over to the following sections to learn more about AudioBookRequest: + +- [Getting Started](/docs/getting-started/): Get started with AudioBookRequest +- [Notifications](/docs/notifications/): Check out some example code! diff --git a/docs/content/docs/concepts/_index.md b/docs/content/docs/concepts/_index.md new file mode 100644 index 0000000..86fed03 --- /dev/null +++ b/docs/content/docs/concepts/_index.md @@ -0,0 +1,6 @@ +--- +title: Concepts +description: > + Concepts used in ABR in more detail. +weight: 4 +--- diff --git a/docs/content/docs/concepts/environment-variables.md b/docs/content/docs/concepts/environment-variables.md new file mode 100644 index 0000000..b7df5c5 --- /dev/null +++ b/docs/content/docs/concepts/environment-variables.md @@ -0,0 +1,20 @@ +--- +title: 'Environment Variables' +description: > + List of the environment variables that can be set. +date: 2025-06-09T13:46:33+02:00 +--- + +| ENV | Description | Default | +| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | +| `ABR_APP__PORT` | The port to run the server on. | 8000 | +| `ABR_APP__DEBUG` | If to enable debug mode. Not recommended for production. | false | +| `ABR_APP__OPENAPI_ENABLED` | If set to `true`, enables an OpenAPI specs page on `/docs`. | false | +| `ABR_APP__CONFIG_DIR` | The directory path where persistant data and configuration is stored. If ran using Docker or Kubernetes, this is the location a volume should be mounted to. | /config | +| `ABR_APP__LOG_LEVEL` | One of `DEBUG`, `INFO`, `WARN`, `ERROR`. | INFO | +| `ABR_APP__BASE_URL` | Defines the base url the website is hosted at. If the website is accessed at `example.org/abr/`, set the base URL to `/abr/` | | +| `ABR_DB__SQLITE_PATH` | If relative, path and name of the sqlite database in relation to `ABR_APP__CONFIG_DIR`. If absolute (path starts with `/`), the config dir is ignored and only the absolute path is used. | db.sqlite | + +{{< alert title="Note" >}} There are two underscores (`__`) between the first +and second part of each environment variable like between `ABR_APP` and `PORT`. +{{< /alert >}} diff --git a/docs/content/docs/contribution-guidelines.md b/docs/content/docs/contribution-guidelines.md new file mode 100644 index 0000000..6207d68 --- /dev/null +++ b/docs/content/docs/contribution-guidelines.md @@ -0,0 +1,88 @@ +--- +title: Contribution Guidelines +description: How to contribute to the docs. +weight: 10 +--- + +We use [Hugo](https://gohugo.io/) to format and generate our website, the +[Docsy](https://github.com/google/docsy) theme for styling and site structure, +and [Github Pages](https://pages.github.com/) to manage the deployment of the +site. Hugo is an open-source static site generator that provides us with +templates, content organisation in a standard directory structure, and a website +generation engine. You write the pages in Markdown (or HTML if you want), and +Hugo wraps them up into a website. + +All submissions require review. We use GitHub pullas requests for this purpose. +Consult [GitHub Help](https://help.github.com/articles/about-pull-requests/) for +more information on using pull requests. + +## Quick start with Hugo + +Here's a quick guide to updating the docs. It assumes you're familiar with the +GitHub workflow and you're happy to use the automated preview of your doc +updates: + +1. Fork the + [AudioBookRequest repo](https://github.com/markbeep/AudioBookRequest) on + GitHub. +1. Make your changes and send a pull request (PR). +1. If you're not yet ready for a review, add "WIP" to the PR name to indicate + it's a work in progress. (**Don't** add the Hugo property "draft = true" to + the page front matter, because that prevents the auto-deployment of the + content preview described in the next point.) +1. When you're ready for a review, add a comment to the PR, and remove any "WIP" + markers. + +## Updating a single page + +If you've just spotted something you'd like to change while using the docs, +Docsy has a shortcut for you: + +1. Click **Edit this page** in the top right hand corner of the page. +1. If you don't already have an up to date fork of the project repo, you are + prompted to get one - click **Fork this repository and propose changes** or + **Update your Fork** to get an up to date version of the project to edit. The + appropriate page in your fork is displayed in edit mode. +1. Follow the rest of the [Quick start with Hugo](#quick-start-with-hugo) + process above to make, preview, and propose your changes. + +## Previewing your changes locally + +If you want to run your own local Hugo server to preview your changes as you +work: + +1. Follow the instructions in [Getting started](/docs/getting-started/docs) to + install Hugo and any other tools you need. You'll need at least **Hugo + version 0.146.0** (we recommend using the most recent available version), and + it must be the **extended** version, which supports SCSS. +2. Fork the + [AudioBookRequest repo](https://github.com/markbeep/AudioBookRequest) into + your own project, then create a local copy using `git clone`. + + ``` + git clone --branch v0.12.0 --depth 1 https://github.com/markbeep/AudioBookRequest.git + ``` + +3. Run `hugo server` in the site root directory. By default your site will be + available at http://localhost:1313/. Now that you're serving your site + locally, Hugo will watch for changes to the content and automatically refresh + your site. +4. Continue with the usual GitHub workflow to edit files, commit them, push the + changes up to your fork, and create a pull request. + +## Creating an issue + +If you've found a problem in the docs, but you're not sure how to fix it +yourself, please create an issue in the +[AudioBookRequest repo](https://github.com/markbeep/AudioBookRequest/issues). +You can also create an issue about a specific page by clicking the **Create +Issue** button in the top right hand corner of the page. + +## Useful resources + +- [Docsy user guide](https://www.docsy.dev/docs/): All about Docsy, including + how it manages navigation, look and feel, and multi-language support. +- [Hugo documentation](https://gohugo.io/documentation/): Comprehensive + reference for Hugo. +- [Github Hello World!](https://guides.github.com/activities/hello-world/): A + basic introduction to GitHub concepts and workflow. diff --git a/docs/content/docs/getting-started/_index.md b/docs/content/docs/getting-started/_index.md new file mode 100644 index 0000000..23271a7 --- /dev/null +++ b/docs/content/docs/getting-started/_index.md @@ -0,0 +1,19 @@ +--- +title: Getting Started +description: What does your user need to know to try your project? +categories: [] +tags: [setup] +weight: 1 +--- + +## Prerequisites + +AudioBookRequest has been packaged as a [Docker](https://www.docker.com/) image +to make it easy to deploy and run on servers. While it is possible to run ABR +without Docker, that option should be avoided if possible and only used for +local development, as a lot of things can change from version to version. + +## Setup + +Head to [Running the app](/docs/getting-started/running-the-app) for +instructions on how to run ABR. diff --git a/docs/content/docs/getting-started/docs.md b/docs/content/docs/getting-started/docs.md new file mode 100644 index 0000000..5dddfa0 --- /dev/null +++ b/docs/content/docs/getting-started/docs.md @@ -0,0 +1,6 @@ +--- +title: "Docs" +date: 2025-06-09T13:52:47+02:00 +draft: true +--- + diff --git a/docs/content/docs/getting-started/running-the-app/_index.md b/docs/content/docs/getting-started/running-the-app/_index.md new file mode 100644 index 0000000..54fa60f --- /dev/null +++ b/docs/content/docs/getting-started/running-the-app/_index.md @@ -0,0 +1,14 @@ +--- +title: Running the app +description: Getting AudioBookRequest up and running. +categories: [Setup] +tags: [] +weight: 1 +--- + +The app has a docker image that simplifies the deployment. The preferred methods +of running the application all revolve around running the Docker image in +different ways. + +Select the method you want to use to deploy below or if your tool is not listed +(for example Portainer), head to the [docker](./docker.md) page. diff --git a/docs/content/docs/getting-started/running-the-app/bare-metal.md b/docs/content/docs/getting-started/running-the-app/bare-metal.md new file mode 100644 index 0000000..a71bd07 --- /dev/null +++ b/docs/content/docs/getting-started/running-the-app/bare-metal.md @@ -0,0 +1,40 @@ +--- +title: 'Bare Metal' +date: 2025-06-09T13:03:35+02:00 +description: > + How to get started **without** Docker. +categories: [Setup] +tags: [development] +weight: 10 +--- + +{{< alert color="warning" title="Warning" >}} The bare metal approach should +only be the last option. Try to get it working with Docker or get support on the +Discord server before trying to set ABR up for a bare metal deployment. + +There are no guarantees that if one version works locally that it won't suddenly +break in the next because of a new dependency, new file structure or something +else. {{< /alert >}} + +To run ABR locally without Docker, the same steps as for the +[local development](/docs/local-development) have to be followed. First, follow +the instructions to get local development working. + +Once local development works, there are a few adjustments that have to be made +to run the app in production mode instead of debug/local mode. + +1. Delete the `.env.local` file or delete all contents in it. +2. Run the python script to fetch and download all required javascript files: + `uv run python /app/util/fetch_js.py`. This should populate your `static/` + directory with some new js files. +3. Instead of running `fastapi dev` you want to execute `fastapi start` to start + the webserver. +4. Create a file called `.env` and place any environment variables you want to + set in there. +5. If you intend to change the port (documented as the env variable + `ABR_APP__PORT`), you'll have to run fastapi with the `--port ` flag: + ```bash + fastapi run --port 5432 + ``` + +With these changes your deployment will be running in production mode. diff --git a/docs/content/docs/getting-started/running-the-app/docker-compose.md b/docs/content/docs/getting-started/running-the-app/docker-compose.md new file mode 100644 index 0000000..1626ee5 --- /dev/null +++ b/docs/content/docs/getting-started/running-the-app/docker-compose.md @@ -0,0 +1,40 @@ +--- +title: 'Docker Compose' +date: 2025-06-09T13:03:35+02:00 +description: > + How to get started using Docker-Compose. +categories: [Setup] +tags: [docker] +weight: 2 +--- + +Docker-compose works the similar way as [Docker](./docker.md). + +The basic docker compose file is as follows: + +```yaml +services: + web: + image: markbeep/audiobookrequest:1 + ports: + - '8000:8000' + volumes: + - ./config:/config +``` + +If you want to add any environment variables, you can add them as explained +[here](https://docs.docker.com/compose/how-tos/environment-variables/set-environment-variables/). +It would look along the lines of this: + +```yaml +services: + web: + image: markbeep/audiobookrequest:1 + ports: + - '8000:5432' + volumes: + - ./config:/config + environment: + ABR_APP__PORT: 5432 + ABR_APP__OPENAPI_ENABLED: true +``` diff --git a/docs/content/docs/getting-started/running-the-app/docker.md b/docs/content/docs/getting-started/running-the-app/docker.md new file mode 100644 index 0000000..fa102dc --- /dev/null +++ b/docs/content/docs/getting-started/running-the-app/docker.md @@ -0,0 +1,33 @@ +--- +title: 'Docker' +date: 2025-06-09T13:03:35+02:00 +description: > + How to get started using Docker. +categories: [Setup] +tags: [docker] +weight: 1 +--- + +If you prefer to run the app manually with docker, you can simply run the +following command: + +```bash +docker run -p 8000:8000 -v $(pwd)/config:/config markbeep/audiobookrequest:1 +``` + +This will start the container on port 8000 and create the `config/` directory in +your current working directory. + +The above command might break on Windows. Instead, use +`${PWD}\config:/config ...` in PowerShell or `%cd%\config:/config ...` in +Windows Command Prompt. + +{{% alert title="Versions" %}}The `:1` at the end denotes the image version. +Check [dockerhub](https://hub.docker.com/r/markbeep/audiobookrequest/tags) for +any other versions you can use instead. + +The `:latest` tag will give you the last non-nightly release, but it is not +recommended incase of changes that are not backwards compatible. + +For experimental builds (latest commits in the `main` branch of the repository), +the `:nightly` version tag can be used. {{% /alert %}} diff --git a/docs/content/docs/getting-started/running-the-app/kubernetes.md b/docs/content/docs/getting-started/running-the-app/kubernetes.md new file mode 100644 index 0000000..181fb64 --- /dev/null +++ b/docs/content/docs/getting-started/running-the-app/kubernetes.md @@ -0,0 +1,46 @@ +--- +title: 'Kubernetes' +date: 2025-06-09T13:03:35+02:00 +description: > + How to get started using Kubernetes. +categories: [Setup] +tags: [docker] +weight: 3 +--- + +Here's an example for a kubernetes deployment file you'd use: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: audiobookrequest + labels: + app: audiobookrequest +spec: + replicas: 1 + selector: + matchLabels: + app: audiobookrequest + template: + metadata: + labels: + app: audiobookrequest + spec: + containers: + - name: audiobookrequest + image: markbeep/audiobookrequest:1 + imagePullPolicy: Always + volumeMounts: + - mountPath: /config + name: abr-config + ports: + - name: http-request + containerPort: 8000 + volumes: + - name: abr-config + hostPath: + path: /mnt/disk/AudioBookRequest/ +``` + +For the volume you can assign it a host path on a node, or assign it to a PVC. diff --git a/docs/content/docs/local-development/_index.md b/docs/content/docs/local-development/_index.md new file mode 100644 index 0000000..e38675d --- /dev/null +++ b/docs/content/docs/local-development/_index.md @@ -0,0 +1,98 @@ +--- +title: Local Development +description: How to set up the project for local development. +categories: [Development] +tags: [local] +weight: 9 +--- + +## Requirements + +- Python >3.12 +- [uv](https://docs.astral.sh/uv/). Used as the package manager +- node.js. Exact version is not too important. Too old versions might fail when + installing packages. + +## Setup + +Virtual environments help isolate any installed packages to this directory. +Project was made with `Python 3.12` and uses new generics introduced in 3.12. +Older python versions might not work or could have incorrect typing. + +For improved dependency management, `uv` is used instead of `pip`. + +```sh +# This creates the venv as well as installs all dependencies +uv sync +``` + +For local development, environment variables can be added to `.env.local` and +they'll be used wherever required. This file is not used in production. + +## Initialize Database + +[Alembic](https://alembic.sqlalchemy.org/en/latest/) is used to create database +migrations. Run the following before starting up the application for the first +time. It will initialize the directory if non-existant, create the database file +as well as execute any required migrations. + +```sh +uv run alembic upgrade heads +``` + +_In case of any model changes, remember to create migrations using +`alembic revision --autogenerate -m ""`._ + +## Generate the CSS files + +[Tailwindcss](https://tailwindcss.com/) is used to style elements using CSS. On +top of that, [daisyUI](https://daisyui.com/) is for easy and consistent +component styling. + +Install daisyUI and start Tailwindcss watcher. Required for any CSS styling. + +```sh +npm i +uv run tailwindcss -i static/tw.css -o static/globals.css --watch +# Alternatively npx can be used to run tailwindcss +npx @tailwindcss/cli@4 -i static/tw.css -o static/globals.css --watch +``` + +Tailwind has to run anytime something is changed in the HTML template files. + +## Run the app + +Running the application is best done in multiple terminals: + +1. Start FastAPI dev mode: + + ```sh + uv run fastapi dev + ``` + + Website can be visited at http://localhost:8000. + +2. _Optional:_ Start browser-sync. This hot reloads the website when the html + template or python files are modified: + +```sh +browser-sync http://localhost:8000 --files templates/** --files app/** +``` + +**NOTE**: Website has to be visited at http://localhost:3000 instead. + +## Docker Compose + +The docker compose can also be used to run the app locally. Any services that +are required can be added to it for easy testing: + +```bash +docker compose up --build +``` + +The local context (ABR) is in a docker compose profile called `local`, which is +only run if explicitly stated as follows: + +```bash +docker compose --profile local up +``` diff --git a/docs/content/docs/tutorials/_index.md b/docs/content/docs/tutorials/_index.md new file mode 100644 index 0000000..d089507 --- /dev/null +++ b/docs/content/docs/tutorials/_index.md @@ -0,0 +1,7 @@ +--- +title: 'Tutorials' +date: 2025-06-09T13:47:04+02:00 +description: > + Tutorials about how to setup certain features with more detail. +weight: 4 +--- diff --git a/docs/content/docs/tutorials/notifications/_index.md b/docs/content/docs/tutorials/notifications/_index.md new file mode 100644 index 0000000..591997b --- /dev/null +++ b/docs/content/docs/tutorials/notifications/_index.md @@ -0,0 +1,8 @@ +--- +title: 'Notifications' +date: 2025-06-09T13:47:04+02:00 +description: > + How to send notifications. +--- + +{{< alert title="Todo" >}}{{< /alert >}} diff --git a/docs/content/docs/tutorials/notifications/discord.md b/docs/content/docs/tutorials/notifications/discord.md new file mode 100644 index 0000000..c1e2bc1 --- /dev/null +++ b/docs/content/docs/tutorials/notifications/discord.md @@ -0,0 +1,8 @@ +--- +title: 'Discord' +description: > + Sending notifications to Discord. +date: 2025-06-09T13:46:58+02:00 +--- + +{{< alert title="Todo" >}}{{< /alert >}} diff --git a/docs/content/search.md b/docs/content/search.md new file mode 100644 index 0000000..394feea --- /dev/null +++ b/docs/content/search.md @@ -0,0 +1,4 @@ +--- +title: Search Results +layout: search +--- diff --git a/docs/docker-compose.yaml b/docs/docker-compose.yaml new file mode 100644 index 0000000..3d56909 --- /dev/null +++ b/docs/docker-compose.yaml @@ -0,0 +1,10 @@ +services: + site: + # image: docsy/docsy-example + build: + context: . + command: server + ports: + - '1313:1313' + volumes: + - .:/src diff --git a/docs/docsy.work b/docs/docsy.work new file mode 100644 index 0000000..074dc2a --- /dev/null +++ b/docs/docsy.work @@ -0,0 +1,5 @@ +go 1.19 + +use . +use ../docsy/ // Local docsy clone resides in sibling folder to this project +// use ./themes/docsy/ // Local docsy clone resides in themes folder diff --git a/docs/docsy.work.sum b/docs/docsy.work.sum new file mode 100644 index 0000000..e69de29 diff --git a/docs/go.mod b/docs/go.mod new file mode 100644 index 0000000..287d709 --- /dev/null +++ b/docs/go.mod @@ -0,0 +1,5 @@ +module github.com/markbeep/AudioBookRequest + +go 1.12 + +require github.com/google/docsy v0.12.0 diff --git a/docs/go.sum b/docs/go.sum new file mode 100644 index 0000000..8a42dcd --- /dev/null +++ b/docs/go.sum @@ -0,0 +1,6 @@ +github.com/FortAwesome/Font-Awesome v0.0.0-20241216213156-af620534bfc3 h1:/iluJkJiyTAdnqrw3Yi9rH2HNHhrrtCmj8VJe7I6o3w= +github.com/FortAwesome/Font-Awesome v0.0.0-20241216213156-af620534bfc3/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo= +github.com/google/docsy v0.12.0 h1:CddZKL39YyJzawr8GTVaakvcUTCJRAAYdz7W0qfZ2P4= +github.com/google/docsy v0.12.0/go.mod h1:1bioDqA493neyFesaTvQ9reV0V2vYy+xUAnlnz7+miM= +github.com/twbs/bootstrap v5.3.6+incompatible h1:efmXVyq839m5QQ0+JBUdQQ1TrmoBqvQ5kRhUueKsH+4= +github.com/twbs/bootstrap v5.3.6+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0= diff --git a/docs/hugo-disabled.toml b/docs/hugo-disabled.toml new file mode 100644 index 0000000..78c81a6 --- /dev/null +++ b/docs/hugo-disabled.toml @@ -0,0 +1,220 @@ +baseURL = "https://example.docsy.dev/" +title = "Goldydocs" + +# Language settings +contentDir = "content/en" +defaultContentLanguage = "en" +defaultContentLanguageInSubdir = false +# Useful when translating. +enableMissingTranslationPlaceholders = true + +enableRobotsTXT = true + +# Will give values to .Lastmod etc. +enableGitInfo = true + +# Comment out to disable taxonomies in Docsy +# disableKinds = ["taxonomy"] + +# You can add your own taxonomies +[taxonomies] +tag = "tags" +category = "categories" + +[params.taxonomy] +# set taxonomyCloud = [] to hide taxonomy clouds +taxonomyCloud = ["tags", "categories"] + +# If used, must have same length as taxonomyCloud +taxonomyCloudTitle = ["Tag Cloud", "Categories"] + +# set taxonomyPageHeader = [] to hide taxonomies on the page headers +taxonomyPageHeader = ["tags", "categories"] + +# Highlighting config +pygmentsCodeFences = true +pygmentsUseClasses = false +# Use the new Chroma Go highlighter in Hugo. +pygmentsUseClassic = false +#pygmentsOptions = "linenos=table" +# See https://help.farbox.com/pygments.html +pygmentsStyle = "tango" + +# Configure how URLs look like per section. +[permalinks] +blog = "/:section/:year/:month/:day/:slug/" + +# Image processing configuration. +[imaging] +resampleFilter = "CatmullRom" +quality = 75 +anchor = "smart" + +# Language configuration + +[languages] +[languages.en] +languageName ="English" +title = "Goldydocs" +[languages.en.params] +description = "A Docsy example site" + +[languages.no] +languageName ="Norsk" +contentDir = "content/no" +title = "Gulldoks" +[languages.no.params] +description = "Docsy er operativsystem for skyen" +time_format_default = "02.01.2006" +time_format_blog = "02.01.2006" + +[languages.fa] +languageDirection = "rtl" +languageName ="فارسی" +contentDir = "content/fa" +title = "اسناد گلدی" +[languages.fa.params] +description = "یک نمونه برای پوسته داکسی" +time_format_default = "2006.01.02" +time_format_blog = "2006.01.02" + +[markup] + [markup.goldmark] + [markup.goldmark.parser.attribute] + block = true + [markup.goldmark.renderer] + unsafe = true + [markup.highlight] + # See a complete list of available styles at https://xyproto.github.io/splash/docs/all.html + style = "tango" + # Uncomment if you want your chosen highlight style used for code blocks without a specified language + # guessSyntax = "true" + +# Comment out if you don't want the "print entire section" link enabled. +[outputs] +section = ["HTML", "print", "RSS"] + +# Everything below this are Site Params + +[params] +privacy_policy = "https://policies.google.com/privacy" + +# First one is picked as the Twitter card image if not set on page. +# images = ["images/project-illustration.png"] + +# Menu title if your navbar has a versions selector to access old versions of your site. +# This menu appears only if you have at least one [params.versions] set. +version_menu = "Releases" + +# Flag used in the "version-banner" partial to decide whether to display a +# banner on every page indicating that this is an archived version of the docs. +# Set this flag to "true" if you want to display the banner. +archived_version = false + +# The version number for the version of the docs represented in this doc set. +# Used in the "version-banner" partial to display a version number for the +# current doc set. +version = "0.7.1" + +# A link to latest version of the docs. Used in the "version-banner" partial to +# point people to the main doc site. +url_latest_version = "https://example.com" + +# Repository configuration (URLs for in-page links to opening issues and suggesting changes) +github_repo = "https://github.com/google/docsy-example" +# An optional link to a related project repo. For example, the sibling repository where your product code lives. +github_project_repo = "https://github.com/google/docsy" + +# Specify a value here if your content directory is not in your repo's root directory +# github_subdir = "" + +# Uncomment this if your GitHub repo does not have "main" as the default branch, +# or specify a new value if you want to reference another branch in your GitHub links +github_branch= "main" + +# Google Custom Search Engine ID. Remove or comment out to disable search. +gcs_engine_id = "d72aa9b2712488cc3" + +# Enable Lunr.js offline search +offlineSearch = false + +# Enable syntax highlighting and copy buttons on code blocks with Prism +prism_syntax_highlighting = false + +[params.copyright] + authors = "Docsy Authors | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0) | " + from_year = 2018 + +# User interface configuration +[params.ui] +# Set to true to disable breadcrumb navigation. +breadcrumb_disable = false +# Set to false if you don't want to display a logo (/assets/icons/logo.svg) in the top navbar +navbar_logo = true +# Set to true if you don't want the top navbar to be translucent when over a `block/cover`, like on the homepage. +navbar_translucent_over_cover_disable = false +# Enable to show the side bar menu in its compact state. +sidebar_menu_compact = false +# Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled) +sidebar_search_disable = false + +# Adds a H2 section titled "Feedback" to the bottom of each doc. The responses are sent to Google Analytics as events. +# This feature depends on [services.googleAnalytics] and will be disabled if "services.googleAnalytics.id" is not set. +# If you want this feature, but occasionally need to remove the "Feedback" section from a single page, +# add "hide_feedback: true" to the page's front matter. +[params.ui.feedback] +enable = true +# The responses that the user sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful). +yes = 'Glad to hear it! Please tell us how we can improve.' +no = 'Sorry to hear that. Please tell us how we can improve.' + +# Adds a reading time to the top of each doc. +# If you want this feature, but occasionally need to remove the Reading time from a single page, +# add "hide_readingtime: true" to the page's front matter +[params.ui.readingtime] +enable = false + +[params.links] +# End user relevant links. These will show up on left side of footer and in the community page if you have one. +[[params.links.user]] + name = "User mailing list" + url = "https://example.org/mail" + icon = "fa fa-envelope" + desc = "Discussion and help from your fellow users" +[[params.links.user]] + name ="Twitter" + url = "https://example.org/twitter" + icon = "fab fa-twitter" + desc = "Follow us on Twitter to get the latest news!" +[[params.links.user]] + name = "Stack Overflow" + url = "https://example.org/stack" + icon = "fab fa-stack-overflow" + desc = "Practical questions and curated answers" +# Developer relevant links. These will show up on right side of footer and in the community page if you have one. +[[params.links.developer]] + name = "GitHub" + url = "https://github.com/google/docsy" + icon = "fab fa-github" + desc = "Development takes place here!" +[[params.links.developer]] + name = "Slack" + url = "https://example.org/slack" + icon = "fab fa-slack" + desc = "Chat with other project developers" +[[params.links.developer]] + name = "Developer mailing list" + url = "https://example.org/mail" + icon = "fa fa-envelope" + desc = "Discuss development issues around the project" + +# hugo module configuration +[module] + # Uncomment the next line to build and serve using local docsy clone declared in the named Hugo workspace: + # workspace = "docsy.work" + [module.hugoVersion] + extended = true + min = "0.146.0" + [[module.imports]] + path = "github.com/google/docsy" + disable = false diff --git a/docs/hugo.yaml b/docs/hugo.yaml new file mode 100644 index 0000000..83c5ddd --- /dev/null +++ b/docs/hugo.yaml @@ -0,0 +1,205 @@ +baseURL: https://markbeep.github.io/ +title: AudioBookRequest + +# cSpell:ignore goldmark github hugo readingtime docsy subdir lastmod pygments linenos catmullrom norsk gu + +# Language settings +contentDir: content +defaultContentLanguage: en +defaultContentLanguageInSubdir: false +# Useful when translating. +enableMissingTranslationPlaceholders: true + +enableRobotsTXT: true + +# Will give values to .Lastmod etc. +enableGitInfo: true + +# Comment out to disable taxonomies in Docsy +# disableKinds: [taxonomy] + +# You can add your own taxonomies +taxonomies: + tag: tags + category: categories + +# Highlighting config +pygmentsCodeFences: true +pygmentsUseClasses: false +# Use the new Chroma Go highlighter in Hugo. +pygmentsUseClassic: false +# pygmentsOptions: "linenos=table" +# See https://help.farbox.com/pygments.html +pygmentsStyle: tango + +# Configure how URLs look like per section. +permalinks: + blog: /:section/:year/:month/:day/:slug/ + +# Image processing configuration. +imaging: + resampleFilter: CatmullRom + quality: 75 + anchor: smart + +# Language configuration +languages: + en: + languageName: English + title: AudioBookRequest Docs + params: + description: + Documentation for AudioBookRequest, a tool to request audiobooks. + # cSpell:enable + +markup: + goldmark: + parser: + attribute: + block: true + renderer: + unsafe: true + highlight: + # See a complete list of available styles at https://xyproto.github.io/splash/docs/all.html + style: doom-one + # Uncomment if you want your chosen highlight style used for code blocks without a specified language + # guessSyntax: true + +# Everything below this are Site Params + +# Comment out if you don't want the "print entire section" link enabled. +outputs: + section: [HTML, print, RSS] + +params: + taxonomy: + # set taxonomyCloud = [] to hide taxonomy clouds + taxonomyCloud: [tags, categories] + + # If used, must have same length as taxonomyCloud + taxonomyCloudTitle: [Tag Cloud, Categories] + + # set taxonomyPageHeader = [] to hide taxonomies on the page headers + taxonomyPageHeader: [tags, categories] + + # privacy_policy: https://policies.google.com/privacy + + # First one is picked as the Twitter card image if not set on page. + # images: [images/project-illustration.png] + + # Menu title if your navbar has a versions selector to access old versions of your site. + # This menu appears only if you have at least one [params.versions] set. + version_menu: Releases + + # Flag used in the "version-banner" partial to decide whether to display a + # banner on every page indicating that this is an archived version of the docs. + # Set this flag to "true" if you want to display the banner. + archived_version: false + + # The version number for the version of the docs represented in this doc set. + # Used in the "version-banner" partial to display a version number for the + # current doc set. + version: 1.4.8 + + # A link to latest version of the docs. Used in the "version-banner" partial to + # point people to the main doc site. + url_latest_version: https://example.com + + # Repository configuration (URLs for in-page links to opening issues and suggesting changes) + github_repo: https://github.com/markbeep/AudioBookRequest + + # An optional link to a related project repo. For example, the sibling repository where your product code lives. + github_project_repo: https://github.com/markbeep/AudioBookRequest + + # Specify a value here if your content directory is not in your repo's root directory + github_subdir: docs + + # Uncomment this if your GitHub repo does not have "main" as the default branch, + # or specify a new value if you want to reference another branch in your GitHub links + github_branch: main + + # Google Custom Search Engine ID. Remove or comment out to disable search. + gcs_engine_id: d72aa9b2712488cc3 + + # Enable Lunr.js offline search + offlineSearch: false + + # Enable syntax highlighting and copy buttons on code blocks with Prism + prism_syntax_highlighting: false + + copyright: + authors: + markbeep | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0) | + from_year: 2025 + + # User interface configuration + ui: + # Set to true to disable breadcrumb navigation. + breadcrumb_disable: false + # Set to false if you don't want to display a logo (/assets/icons/logo.svg) in the top navbar + navbar_logo: true + # Set to true if you don't want the top navbar to be translucent when over a `block/cover`, like on the homepage. + navbar_translucent_over_cover_disable: false + # Enable to show the side bar menu in its compact state. + sidebar_menu_compact: false + # Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled) + sidebar_search_disable: false + + # Adds a H2 section titled "Feedback" to the bottom of each doc. The responses are sent to Google Analytics as events. + # This feature depends on [services.googleAnalytics] and will be disabled if "services.googleAnalytics.id" is not set. + # If you want this feature, but occasionally need to remove the "Feedback" section from a single page, + # add "hide_feedback: true" to the page's front matter. + feedback: + enable: true + # The responses that the user sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful). + 'yes': >- + Glad to hear it! Please tell us + how we can improve. + 'no': >- + Sorry to hear that. Please tell us + how we can improve. + + # Adds a reading time to the top of each doc. + # If you want this feature, but occasionally need to remove the Reading time from a single page, + # add "hide_readingtime: true" to the page's front matter + readingtime: + enable: false + showLightDarkModeMenu: true + + links: + # End user relevant links. These will show up on left side of footer and in the community page if you have one. + user: + # - name: User mailing list + # url: https://example.org/mail + # icon: fa fa-envelope + # desc: Discussion and help from your fellow users + # - name: Twitter + # url: https://example.org/twitter + # icon: fab fa-twitter + # desc: Follow us on Twitter to get the latest news! + # - name: Stack Overflow + # url: https://example.org/stack + # icon: fab fa-stack-overflow + # desc: Practical questions and curated answers + - name: Discord + url: https://discord.gg/SsFRXWMg7s + icon: fab fa-discord + desc: Chat with others and get support here! + # Developer relevant links. These will show up on right side of footer and in the community page if you have one. + developer: + - name: GitHub + url: https://github.com/google/docsy + icon: fab fa-github + desc: Development takes place here! + +module: + # Uncomment the next line to build and serve using local docsy clone declared in the named Hugo workspace: + # workspace: docsy.work + hugoVersion: + extended: true + min: 0.146.0 + imports: + - path: github.com/google/docsy + disable: false diff --git a/docs/layouts/404.html b/docs/layouts/404.html new file mode 100644 index 0000000..1a9bd70 --- /dev/null +++ b/docs/layouts/404.html @@ -0,0 +1,7 @@ +{{ define "main" -}} +
+

Not found

+

Oops! This page doesn't exist. Try going back to the home page.

+

You can learn how to make a 404 page like this in Custom 404 Pages.

+
+{{- end }} diff --git a/docs/layouts/_markup/render-heading.html b/docs/layouts/_markup/render-heading.html new file mode 100644 index 0000000..24352cb --- /dev/null +++ b/docs/layouts/_markup/render-heading.html @@ -0,0 +1 @@ +{{ partial "td/render-heading.html" . }} diff --git a/docs/package.json b/docs/package.json new file mode 100644 index 0000000..42f8b4b --- /dev/null +++ b/docs/package.json @@ -0,0 +1,52 @@ +{ + "name": "docsy-example-site", + "version": "0.12.0", + "version.next": "0.12.1-dev-unreleased", + "description": "Example site that uses Docsy theme for technical documentation.", + "repository": "github:google/docsy-example", + "homepage": "https://example.docsy.dev", + "author": "Docsy Authors", + "license": "Apache-2.0", + "bugs": "https://github.com/google/docsy-example/issues", + "spelling": "cSpell:ignore docsy hugo htmltest precheck postbuild rtlcss -", + "scripts": { + "_build": "npm run _hugo-dev --", + "_check:links": "echo IMPLEMENTATION PENDING for check-links; echo", + "_hugo": "hugo --cleanDestinationDir", + "_hugo-dev": "npm run _hugo -- -e dev -DFE", + "_local": "npx cross-env HUGO_MODULE_WORKSPACE=docsy.work", + "_serve": "npm run _hugo-dev -- --minify serve --renderToMemory", + "build:preview": "npm run _hugo-dev -- --minify --baseURL \"${DEPLOY_PRIME_URL:-/}\"", + "build:production": "npm run _hugo -- --minify", + "build": "npm run _build -- ", + "check:links:all": "HTMLTEST_ARGS= npm run _check:links", + "check:links": "npm run _check:links", + "clean": "rm -Rf public/* resources", + "local": "npm run _local -- npm run", + "make:public": "git init -b main public", + "precheck:links:all": "npm run build", + "precheck:links": "npm run build", + "postbuild:preview": "npm run _check:links", + "postbuild:production": "npm run _check:links", + "serve": "npm run _serve", + "test": "npm run check:links", + "update:dep": "npm install --save-dev autoprefixer@latest postcss-cli@latest", + "update:hugo": "npm install --save-dev --save-exact hugo-extended@latest", + "update:pkgs": "npx npm-check-updates -u" + }, + "devDependencies": { + "autoprefixer": "^10.4.21", + "cross-env": "^7.0.3", + "hugo-extended": "0.147.6", + "postcss-cli": "^11.0.1", + "rtlcss": "^4.3.0" + }, + "optionalDependencies": { + "npm-check-updates": "^18.0.1" + }, + "private": true, + "prettier": { + "proseWrap": "always", + "singleQuote": true + } +} diff --git a/flake.lock b/flake.lock index fcb87f7..d30846b 100644 --- a/flake.lock +++ b/flake.lock @@ -20,11 +20,11 @@ }, "nixpkgs": { "locked": { - "lastModified": 1743448293, - "narHash": "sha256-bmEPmSjJakAp/JojZRrUvNcDX2R5/nuX6bm+seVaGhs=", + "lastModified": 1749285348, + "narHash": "sha256-frdhQvPbmDYaScPFiCnfdh3B/Vh81Uuoo0w5TkWmmjU=", "owner": "NixOS", "repo": "nixpkgs", - "rev": "77b584d61ff80b4cef9245829a6f1dfad5afdfa3", + "rev": "3e3afe5174c561dee0df6f2c2b2236990146329f", "type": "github" }, "original": { @@ -47,11 +47,11 @@ ] }, "locked": { - "lastModified": 1742689179, - "narHash": "sha256-kDXV6r6pQp6sxBKKxXqcTGPdiH63m8WA+IvzHhdZlEg=", + "lastModified": 1748562898, + "narHash": "sha256-STk4QklrGpM3gliPKNJdBLSQvIrqRuwHI/rnYb/5rh8=", "owner": "pyproject-nix", "repo": "build-system-pkgs", - "rev": "5c2a1faadc4015d50eb9919a8e20c112f3765fc2", + "rev": "33bd58351957bb52dd1700ea7eeefe34de06a892", "type": "github" }, "original": { @@ -67,11 +67,11 @@ ] }, "locked": { - "lastModified": 1743438845, - "narHash": "sha256-1GSaoubGtvsLRwoYwHjeKYq40tLwvuFFVhGrG8J9Oek=", + "lastModified": 1746540146, + "narHash": "sha256-QxdHGNpbicIrw5t6U3x+ZxeY/7IEJ6lYbvsjXmcxFIM=", "owner": "pyproject-nix", "repo": "pyproject.nix", - "rev": "8063ec98edc459571d042a640b1c5e334ecfca1e", + "rev": "e09c10c24ebb955125fda449939bfba664c467fd", "type": "github" }, "original": { @@ -114,11 +114,11 @@ ] }, "locked": { - "lastModified": 1743583530, - "narHash": "sha256-H1QTqUtASQL1wTKEOS+sCUedu2CQ0PvU7/Elqg1jIhw=", + "lastModified": 1749170547, + "narHash": "sha256-zOptuFhTr9P0A+unFaOBFx5E5T6yx0qE8VrUGVrM96U=", "owner": "pyproject-nix", "repo": "uv2nix", - "rev": "ffb8844276870057f85a09dcb8f4e0fab00528e7", + "rev": "7ae60727d4fc2e41aefd30da665e4f92ba8298f1", "type": "github" }, "original": { diff --git a/flake.nix b/flake.nix index d03b464..e265a9b 100644 --- a/flake.nix +++ b/flake.nix @@ -150,11 +150,12 @@ devShells.default = pkgs.mkShell { venvDir = ".venv"; packages = with pkgs; [ - nodejs_23 + nodejs_24 sqlite nodePackages.browser-sync python312Packages.venvShellHook uv + hugo ]; postShellHook = "uv sync"; };