From 04eb136ab0bf185ebdc47e9ab7e43afb7b32c698 Mon Sep 17 00:00:00 2001 From: Matt Kilgore Date: Thu, 27 Jun 2024 22:05:36 -0400 Subject: [PATCH] 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 a9b5f89f8..385946124 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 e9af902bb..000000000 --- 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 000000000..0a8fdd652 --- /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 000000000..439074693 --- /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 0bcb87574..a629290fa 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 00163d498..c71c0b025 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 000000000..88aec5054 --- /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 37abaf456..243f2b204 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" +}