From 04eb136ab0bf185ebdc47e9ab7e43afb7b32c698 Mon Sep 17 00:00:00 2001 From: Matt Kilgore Date: Thu, 27 Jun 2024 22:05:36 -0400 Subject: [PATCH 1/9] feat(docs): i18n support added to docs --- docs/.vitepress/config.mts | 48 ++++++++++++++------- docs/build.md | 15 ------- docs/en/contribute/bounty.md | 19 +++++++++ docs/en/contribute/get-started.md | 69 +++++++++++++++++++++++++++++++ docs/{ => en}/import-csv.md | 0 docs/{ => en}/index.md | 4 +- docs/{ => en}/quick-start.md | 0 docs/{ => en}/tips-tricks.md | 2 +- docs/public/_redirects | 4 ++ package.json | 5 ++- 10 files changed, 130 insertions(+), 36 deletions(-) delete mode 100644 docs/build.md create mode 100644 docs/en/contribute/bounty.md create mode 100644 docs/en/contribute/get-started.md rename docs/{ => en}/import-csv.md (100%) rename docs/{ => en}/index.md (98%) rename docs/{ => en}/quick-start.md (100%) rename docs/{ => en}/tips-tricks.md (97%) create mode 100644 docs/public/_redirects diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index a9b5f89f..38594612 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -8,6 +8,14 @@ export default defineConfig({ sitemap: { hostname: 'https://homebox.sysadminsmedia.com', }, + + locales: { + en: { + label: 'English', + lang: 'en', + } + }, + themeConfig: { logo: '/lilbox.svg', @@ -23,22 +31,30 @@ export default defineConfig({ { text: 'API', link: 'https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/sysadminsmedia/homebox/main/docs/docs/api/openapi-2.0.json' } ], - sidebar: [ - { - text: 'Getting Started', - items: [ - { text: 'Quick Start', link: '/quick-start' }, - { text: 'Tips and Tricks', link: '/tips-tricks' } - ] - }, - { - text: 'Advanced', - items: [ - { text: 'Import CSV', link: '/import-csv' }, - { text: 'Build from Source', link: '/build' } - ] - }, - ], + sidebar: { + '/en/': [ + { + text: 'Getting Started', + items: [ + { text: 'Quick Start', link: '/en/quick-start' }, + { text: 'Tips and Tricks', link: '/en/tips-tricks' } + ] + }, + { + text: 'Advanced', + items: [ + { text: 'Import CSV', link: '/en/import-csv' }, + ] + }, + { + text: 'Contributing', + items: [ + { text: 'Get Started', link: '/en/contribute/get-started' }, + { text: 'Bounty Program', link: '/en/contribute/bounty' } + ] + } + ] + }, socialLinks: [ { icon: 'discord', link: 'https://discord.gg/aY4DCkpNA9' }, diff --git a/docs/build.md b/docs/build.md deleted file mode 100644 index e9af902b..00000000 --- a/docs/build.md +++ /dev/null @@ -1,15 +0,0 @@ -# Building The Binary - -This document describes how to build the project from source code. - -## Prerequisites - -TODO - -## Building - -TODO - -## Running - -TODO \ No newline at end of file diff --git a/docs/en/contribute/bounty.md b/docs/en/contribute/bounty.md new file mode 100644 index 00000000..0a8fdd65 --- /dev/null +++ b/docs/en/contribute/bounty.md @@ -0,0 +1,19 @@ +# Bounty Program + +## About +As part of our commitment to open source, and building an active community around Homebox (and hopefully active pool of developers), we are enabling bounties on issues. + +After digging through several platforms we ended up settling on https://www.boss.dev/ as it has some of the lowest fees we could possibly find for any of these platforms other than spinning one up ourselves (which we currently aren't in a position to do). + +While it's not the perfect solution, we think it's about the best one we could find at the moment to lower the rates as much as possible to make sure everyone get's the highest payouts possible. (Some we found were as high as a combined 16%!!!) + +We hope that by enabling bounties on issues that people who have the means and want certain features implemented quicker can sponsor issues, and in turn everyone contributing code can potentially earn some money for their hard work. + +## Contributor +As a contributor wanting to accept money from bounties you simply need to register for an account via GitHub, and attach a bank account (or debit card in the USA). + +## Sponsor +Sign in with a GitHub account, and then attach a credit card to your account. + +## Commands to use boss.dev +There is documentation on their website regarding commands that you can put in comments to use the bounty system. https://www.boss.dev/doc/ \ No newline at end of file diff --git a/docs/en/contribute/get-started.md b/docs/en/contribute/get-started.md new file mode 100644 index 00000000..43907469 --- /dev/null +++ b/docs/en/contribute/get-started.md @@ -0,0 +1,69 @@ +# Getting Started With Contributing + +## Get Started + +### Prerequisites + +There is a devcontainer available for this project. If you are using VSCode, you can use the devcontainer to get started. If you are not using VSCode, you need to ensure that you have the following tools installed: + +- [Go 1.19+](https://golang.org/doc/install) +- [Swaggo](https://github.com/swaggo/swag) +- [Node.js 16+](https://nodejs.org/en/download/) +- [pnpm](https://pnpm.io/installation) +- [Taskfile](https://taskfile.dev/#/installation) (Optional but recommended) +- For code generation, you'll need to have `python3` available on your path. In most cases, this is already installed and available. + +If you're using `taskfile` you can run `task --list-all` for a list of all commands and their descriptions. + +### Setup + +If you're using the taskfile, you can use the `task setup` command to run the required setup commands. Otherwise, you can review the commands required in the `Taskfile.yml` file. + +Note that when installing dependencies with pnpm you must use the `--shamefully-hoist` flag. If you don't use this flag, you will get an error when running the frontend server. + +### API Development Notes +start command `task go:run` + +1. API Server does not auto reload. You'll need to restart the server after making changes. +2. Unit tests should be written in Go, however, end-to-end or user story tests should be written in TypeScript using the client library in the frontend directory. + +test command `task go:test` + +lint command `task go:lint` + +swagger update command `task swag` + +### Frontend Development Notes + +start command `task: ui:dev` + +1. The frontend is a Vue 3 app with Nuxt.js that uses Tailwind and DaisyUI for styling. +2. We're using Vitest for our automated testing. You can run these with `task ui:watch`. +3. Tests require the API server to be running, and in some cases the first run will fail due to a race condition. If this happens, just run the tests again and they should pass. + +fix/lint code `task ui:fix` + +type checking `task ui:check` + +## Documentation +We use [Vitepress](https://vitepress.dev/) for the web documentation of homebox. Anyone is welcome to contribute the documentation if they wish. +For documentation contributions you only need NodeJS and PNPM. + +::: info Notes +- Languages are seperated by folder (e.g `/en`, `/fr`, etc.) +- The Sidebar must be updated on a per language basis +- Each languages files can be named independently (slugs can match the language) +- The `public/_redirects` file is used to redirect the default to english +- Redirects can also be configured per language by adding `Language=` after the redirect code +::: + +## Branch Flow +We use the `main` branch as the development branch. All PRs should be made to the `main` branch form a feature branch. +To create a pull request you can use the following steps: + +1. Fork the repo and create a new branch from `main` +2. If you added code that should be tested, add tests +3. If you've changed APIs update the documentation +4. Ensure that the test suite and linters pass +5. Create your PR + diff --git a/docs/import-csv.md b/docs/en/import-csv.md similarity index 100% rename from docs/import-csv.md rename to docs/en/import-csv.md diff --git a/docs/index.md b/docs/en/index.md similarity index 98% rename from docs/index.md rename to docs/en/index.md index 0bcb8757..a629290f 100644 --- a/docs/index.md +++ b/docs/en/index.md @@ -11,10 +11,10 @@ hero: actions: - theme: brand text: Quick Start - link: /quick-start + link: /en/quick-start - theme: alt text: Tips and Tricks - link: /tips-tricks + link: /en/tips-tricks features: - title: Add/Update/Delete Items diff --git a/docs/quick-start.md b/docs/en/quick-start.md similarity index 100% rename from docs/quick-start.md rename to docs/en/quick-start.md diff --git a/docs/tips-tricks.md b/docs/en/tips-tricks.md similarity index 97% rename from docs/tips-tricks.md rename to docs/en/tips-tricks.md index 00163d49..c71c0b02 100644 --- a/docs/tips-tricks.md +++ b/docs/en/tips-tricks.md @@ -17,7 +17,7 @@ Homebox Custom Fields also have special support for URLs. Provide a URL (`https: ## Managing Asset IDs -Homebox provides the option to auto-set asset IDs, this is the default behavior. These can be used for tracking assets with printable tags or labels. You can disable this behavior via a command line flag or ENV variable. See [configuration](/quick-start#env-variables-configuration) for more details. +Homebox provides the option to auto-set asset IDs, this is the default behavior. These can be used for tracking assets with printable tags or labels. You can disable this behavior via a command line flag or ENV variable. See [configuration](/docs/en/quick-start.md#env-variables-configuration) for more details. Example ID: `000-001` diff --git a/docs/public/_redirects b/docs/public/_redirects new file mode 100644 index 00000000..88aec505 --- /dev/null +++ b/docs/public/_redirects @@ -0,0 +1,4 @@ +/* /en/:splat 302 + +# This is an example for a french redirect +# /* /fr/:splat 302 Language=fr \ No newline at end of file diff --git a/package.json b/package.json index 37abaf45..243f2b20 100644 --- a/package.json +++ b/package.json @@ -14,5 +14,6 @@ "license": "ISC", "devDependencies": { "vitepress": "^1.2.3" - } -} \ No newline at end of file + }, + "packageManager": "pnpm@9.1.4+sha512.9df9cf27c91715646c7d675d1c9c8e41f6fce88246f1318c1aa6a1ed1aeb3c4f032fcdf4ba63cc69c4fe6d634279176b5358727d8f2cc1e65b65f43ce2f8bfb0" +} From a0198fb66f46fa4cef7258ee4ab4805b9925cef6 Mon Sep 17 00:00:00 2001 From: Matt Kilgore Date: Thu, 27 Jun 2024 22:07:32 -0400 Subject: [PATCH 2/9] fix(docs): broken link --- docs/en/tips-tricks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/tips-tricks.md b/docs/en/tips-tricks.md index c71c0b02..5a2f556e 100644 --- a/docs/en/tips-tricks.md +++ b/docs/en/tips-tricks.md @@ -17,7 +17,7 @@ Homebox Custom Fields also have special support for URLs. Provide a URL (`https: ## Managing Asset IDs -Homebox provides the option to auto-set asset IDs, this is the default behavior. These can be used for tracking assets with printable tags or labels. You can disable this behavior via a command line flag or ENV variable. See [configuration](/docs/en/quick-start.md#env-variables-configuration) for more details. +Homebox provides the option to auto-set asset IDs, this is the default behavior. These can be used for tracking assets with printable tags or labels. You can disable this behavior via a command line flag or ENV variable. See [configuration](/en/quick-start.md#env-variables-configuration) for more details. Example ID: `000-001` From 7b9c3d52cd331eb046b6d85f2f82050055e272e4 Mon Sep 17 00:00:00 2001 From: Matt Kilgore Date: Thu, 27 Jun 2024 22:09:22 -0400 Subject: [PATCH 3/9] fix(docs): redirect default to english --- docs/public/_redirects | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/public/_redirects b/docs/public/_redirects index 88aec505..969116f3 100644 --- a/docs/public/_redirects +++ b/docs/public/_redirects @@ -1,3 +1,4 @@ +/ /en/ 302 /* /en/:splat 302 # This is an example for a french redirect From 8b8a96f93b0e420260f35181b942ffdad9be4bd2 Mon Sep 17 00:00:00 2001 From: Matt Kilgore Date: Thu, 27 Jun 2024 22:10:19 -0400 Subject: [PATCH 4/9] fix(docs): redirect default to english --- docs/public/_redirects | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/public/_redirects b/docs/public/_redirects index 969116f3..5735b374 100644 --- a/docs/public/_redirects +++ b/docs/public/_redirects @@ -1,5 +1,4 @@ / /en/ 302 -/* /en/:splat 302 # This is an example for a french redirect # /* /fr/:splat 302 Language=fr \ No newline at end of file From 40a093656badd271e6b13fae940d47c1e9311302 Mon Sep 17 00:00:00 2001 From: Matt Kilgore Date: Thu, 27 Jun 2024 22:13:09 -0400 Subject: [PATCH 5/9] chore(docs): remove home link (it's broken) --- docs/.vitepress/config.mts | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 38594612..7bd5000c 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -27,7 +27,6 @@ export default defineConfig({ }, // https://vitepress.dev/reference/default-theme-config nav: [ - { text: 'Home', link: '/' }, { text: 'API', link: 'https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/sysadminsmedia/homebox/main/docs/docs/api/openapi-2.0.json' } ], From 0f25983278a0eb1e63a3286b4ad48a3125230f96 Mon Sep 17 00:00:00 2001 From: Katos <7927609+katosdev@users.noreply.github.com> Date: Sat, 29 Jun 2024 18:03:07 +0100 Subject: [PATCH 6/9] Improve link readability in Markdown --- docs/en/contribute/bounty.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/contribute/bounty.md b/docs/en/contribute/bounty.md index 0a8fdd65..5b0e4514 100644 --- a/docs/en/contribute/bounty.md +++ b/docs/en/contribute/bounty.md @@ -3,7 +3,7 @@ ## About As part of our commitment to open source, and building an active community around Homebox (and hopefully active pool of developers), we are enabling bounties on issues. -After digging through several platforms we ended up settling on https://www.boss.dev/ as it has some of the lowest fees we could possibly find for any of these platforms other than spinning one up ourselves (which we currently aren't in a position to do). +After digging through several platforms we ended up settling on [boss.dev](https://www.boss.dev/) as it has some of the lowest fees we could possibly find for any of these platforms other than spinning one up ourselves (which we currently aren't in a position to do). While it's not the perfect solution, we think it's about the best one we could find at the moment to lower the rates as much as possible to make sure everyone get's the highest payouts possible. (Some we found were as high as a combined 16%!!!) @@ -16,4 +16,4 @@ As a contributor wanting to accept money from bounties you simply need to regist Sign in with a GitHub account, and then attach a credit card to your account. ## Commands to use boss.dev -There is documentation on their website regarding commands that you can put in comments to use the bounty system. https://www.boss.dev/doc/ \ No newline at end of file +There is documentation on their website regarding commands that you can put in comments to use the bounty system. [boss.dev Documentation](https://www.boss.dev/doc) From 0b7de9557d8ba79f28cb8aaafb58300e4fd37a9a Mon Sep 17 00:00:00 2001 From: Katos <7927609+katosdev@users.noreply.github.com> Date: Sat, 29 Jun 2024 18:04:14 +0100 Subject: [PATCH 7/9] Minor grammar change --- docs/en/contribute/bounty.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/contribute/bounty.md b/docs/en/contribute/bounty.md index 5b0e4514..570d33ab 100644 --- a/docs/en/contribute/bounty.md +++ b/docs/en/contribute/bounty.md @@ -3,7 +3,7 @@ ## About As part of our commitment to open source, and building an active community around Homebox (and hopefully active pool of developers), we are enabling bounties on issues. -After digging through several platforms we ended up settling on [boss.dev](https://www.boss.dev/) as it has some of the lowest fees we could possibly find for any of these platforms other than spinning one up ourselves (which we currently aren't in a position to do). +After digging through several platforms, we ended up settling on [boss.dev](https://www.boss.dev/) as it has some of the lowest fees we could possibly find for any of these platforms other than spinning one up ourselves (which we currently aren't in a position to do). While it's not the perfect solution, we think it's about the best one we could find at the moment to lower the rates as much as possible to make sure everyone get's the highest payouts possible. (Some we found were as high as a combined 16%!!!) From 76123e00d6fed72b6122a6eeb535cbc05338e983 Mon Sep 17 00:00:00 2001 From: Katos <7927609+katosdev@users.noreply.github.com> Date: Sat, 29 Jun 2024 18:06:44 +0100 Subject: [PATCH 8/9] Minor rewording --- docs/en/contribute/bounty.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/contribute/bounty.md b/docs/en/contribute/bounty.md index 570d33ab..bb1eab62 100644 --- a/docs/en/contribute/bounty.md +++ b/docs/en/contribute/bounty.md @@ -7,10 +7,10 @@ After digging through several platforms, we ended up settling on [boss.dev](http While it's not the perfect solution, we think it's about the best one we could find at the moment to lower the rates as much as possible to make sure everyone get's the highest payouts possible. (Some we found were as high as a combined 16%!!!) -We hope that by enabling bounties on issues that people who have the means and want certain features implemented quicker can sponsor issues, and in turn everyone contributing code can potentially earn some money for their hard work. +We hope that by enabling bounties on issues, people who have the means and want certain features implemented quicker can now sponsor issues, and in turn everyone contributing code can potentially earn some money for their hard work. ## Contributor -As a contributor wanting to accept money from bounties you simply need to register for an account via GitHub, and attach a bank account (or debit card in the USA). +As a contributor wanting to accept money from bounties all you need to do is simply register for an account via GitHub, and attach a bank account (or debit card in the USA). ## Sponsor Sign in with a GitHub account, and then attach a credit card to your account. From 4995e04cf034c0d99fb8526d34e7a8328d6a9428 Mon Sep 17 00:00:00 2001 From: Katos <7927609+katosdev@users.noreply.github.com> Date: Sat, 29 Jun 2024 18:07:35 +0100 Subject: [PATCH 9/9] Appease the bot overlords. --- docs/en/contribute/get-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/contribute/get-started.md b/docs/en/contribute/get-started.md index 43907469..cae20d22 100644 --- a/docs/en/contribute/get-started.md +++ b/docs/en/contribute/get-started.md @@ -19,7 +19,7 @@ If you're using `taskfile` you can run `task --list-all` for a list of all comma If you're using the taskfile, you can use the `task setup` command to run the required setup commands. Otherwise, you can review the commands required in the `Taskfile.yml` file. -Note that when installing dependencies with pnpm you must use the `--shamefully-hoist` flag. If you don't use this flag, you will get an error when running the frontend server. +Note that when installing dependencies with pnpm, you must use the `--shamefully-hoist` flag. If you don't use this flag, you will get an error when running the frontend server. ### API Development Notes start command `task go:run`