From 57290e679ef95cd44532fef0f39e3da4c1ab471c Mon Sep 17 00:00:00 2001 From: Nigel Breslaw Date: Tue, 26 Dec 2023 16:08:23 +0100 Subject: [PATCH] Improve the docs --- README.md | 19 ------------ docs/starlight/astro.config.mjs | 15 ++++++++-- .../src/content/docs/guides/cloudflare.md | 12 ++++++++ .../content/docs/guides/getting-started.md | 17 ++++++++--- docs/starlight/src/content/docs/index.mdx | 10 +++---- .../src/content/docs/reference/costs.md | 29 +++++++++++++++++++ .../src/content/docs/reference/example.md | 11 ------- docs/starlight/src/content/docs/tech/ci.md | 19 ++++++++++++ docs/starlight/src/content/docs/tech/misc.md | 6 ++++ 9 files changed, 97 insertions(+), 41 deletions(-) create mode 100644 docs/starlight/src/content/docs/guides/cloudflare.md create mode 100644 docs/starlight/src/content/docs/reference/costs.md delete mode 100644 docs/starlight/src/content/docs/reference/example.md create mode 100644 docs/starlight/src/content/docs/tech/ci.md create mode 100644 docs/starlight/src/content/docs/tech/misc.md diff --git a/README.md b/README.md index c0d0ffcc7..7bdcbab38 100644 --- a/README.md +++ b/README.md @@ -2,30 +2,11 @@ As of Decemeber 2023 this is a monorepo built around going beyond the Ishtar Commander mobile applications. -The current short term plans are: - -- [x] Setup github page and have a running CI. -- [x] Register the new domains. -- [] Learn how to setup a cloudflare D1 database and record CI related data. -- [] Setup a mini stats [dashboard](https://dashboard.guardianghost.com). -- [] Setup a mini [documentation](https://documentation.guardianghost.com) site. MKdocs or Starlight are options. -- [] Start with a React app for the main app. However React Native has potential for hitting mobile, desktop and web. - The tech choices are based on interesting new tools to learn. However the main app will use React. ## Developer environment -I did try to use [Bun](https://bun.sh/) which limits development to Linux and MacOS with Windows support only on [WSL](https://learn.microsoft.com/en-us/windows/wsl/about). However the monorepo and full node ecosystem support isn't quite there yet. Thus Node and [Pnpm](https://pnpm.io) are used instead. CI runs as of 25.12.2023 are ~25 seconds with PNPM and probably would be 5-8 seconds faster with Bun. I will revisit Bun later in 2024 when its compatibility and Monorepo support improves. - - -## CI / DevOps -The CI is powerered by github acctions and the aims are: -1. Full CI run should only take 1 min for the entire monorepo. -2. CI costs should happily fit inside githubs free tier. That's 2000 minutes a month. However none of these minutes is currently used as runs that take under a minute don't seem to count towards this total. -3. Try and use some of the new generation of Rust based tools to keep every stage as fast as possible. -[Dependabot](https://github.com/dependabot) is enabled on the repo and runs everyday. In general the number of dependencies is kept as low as possible. However the aim is to only have items updated on a weekly basis. -[Sonarqube](https://sonarcloud.io/organizations/nigelbreslaw/projects) offers a free tier for public projects and runs as a quality gate on every PR. diff --git a/docs/starlight/astro.config.mjs b/docs/starlight/astro.config.mjs index 3102d30ba..8b1297bd3 100644 --- a/docs/starlight/astro.config.mjs +++ b/docs/starlight/astro.config.mjs @@ -10,16 +10,27 @@ export default defineConfig({ github: 'https://github.com/NigelBreslaw/guardian-ghost', }, sidebar: [ + { + label: 'Technologies', + items: [ + { label: 'CI', link: '/tech/ci/' }, + { label: 'Misc', link: '/tech/misc/' }, + ] + }, { label: 'Guides', items: [ // Each item here is one entry in the navigation menu. - { label: 'Example Guide', link: '/guides/example/' }, + { label: 'Getting started', link: '/guides/getting-started/' }, + { label: 'Cloudflare', link: '/guides/cloudflare/' }, + ], }, { label: 'Reference', - autogenerate: { directory: 'reference' }, + items: [ + { label: 'Costs', link: '/reference/costs/' }, + ] }, ], }), diff --git a/docs/starlight/src/content/docs/guides/cloudflare.md b/docs/starlight/src/content/docs/guides/cloudflare.md new file mode 100644 index 000000000..566807294 --- /dev/null +++ b/docs/starlight/src/content/docs/guides/cloudflare.md @@ -0,0 +1,12 @@ +--- +title: Cloudflare +description: Details of how the cloudflare setup works +--- + +This section records how the [Cloudflare]() setup works to avoid having to relearn this in the future. + + + + + + diff --git a/docs/starlight/src/content/docs/guides/getting-started.md b/docs/starlight/src/content/docs/guides/getting-started.md index 790756037..7266092f6 100644 --- a/docs/starlight/src/content/docs/guides/getting-started.md +++ b/docs/starlight/src/content/docs/guides/getting-started.md @@ -3,9 +3,18 @@ title: Getting Started description: Instructions for setting up the Guardian Ghost monorepo and dev environment --- -Guides lead a user through a specific task they want to accomplish, often with a sequence of steps. -Writing a good guide requires thinking about what your users are trying to do. +Guardian Ghost is setup as a monorepo. -## Further reading +The following setup presumes you are using Git Worktree. If that is new to you check out this quick [video](https://www.youtube.com/watch?v=2uEqYw-N8uE). -- Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework +First bare clone the repo `git clone --bare git@github.com:NigelBreslaw/guardian-ghost.git`. + +Then cd in `cd guardian-ghost.git` and setup the origin `git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"` or git fetch won't work as expected. + +When pushing a new branch you will see 'current branch has no upstream branch, blah blah blah'. As of git 2.37.0 and higher you can setup auto tracking and never have to deal with this again! `git config --global push.autoSetupRemote true` + + + +## TODO + +Create a bash script that checks you have the right version of various tools such as git, xcode, etc and clones and sets everything up for you. diff --git a/docs/starlight/src/content/docs/index.mdx b/docs/starlight/src/content/docs/index.mdx index 9ed8579bf..5c307e518 100644 --- a/docs/starlight/src/content/docs/index.mdx +++ b/docs/starlight/src/content/docs/index.mdx @@ -3,16 +3,16 @@ title: GG Guardian Ghost docs description: Built using Astro Starlight template: splash hero: - tagline: Currently this is just the Starlight starter template + tagline: Developer focused documentation image: file: ../../assets/guardian-loot.webp actions: - - text: Example Guide - link: /guides/example/ + - text: Getting started + link: /guides/getting-started/ icon: right-arrow variant: primary - - text: Read the Starlight docs - link: https://starlight.astro.build + - text: Visit the main Guardian Ghost page + link: https://guardianghost.com icon: external --- diff --git a/docs/starlight/src/content/docs/reference/costs.md b/docs/starlight/src/content/docs/reference/costs.md new file mode 100644 index 000000000..f453a8e1c --- /dev/null +++ b/docs/starlight/src/content/docs/reference/costs.md @@ -0,0 +1,29 @@ +--- +title: Costs +description: Current yearly tool and hosting costs for developing Guardian Ghost +--- + +### Hosting +Source code: Github (free) + +Web apps: Cloudflare Pages (free) + + +### App Stores and SDK +Windows and Android are either free or were a one off fee paid years ago. +Apple (iOS and MacOS): $99 a year. + + +### Domain registration +.com and .app yearly fees are ~$20 a year + +# Yearly total +$120 + + + + + + + + diff --git a/docs/starlight/src/content/docs/reference/example.md b/docs/starlight/src/content/docs/reference/example.md deleted file mode 100644 index ac8cfa8bc..000000000 --- a/docs/starlight/src/content/docs/reference/example.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Example Reference -description: A reference page in my new Starlight docs site. ---- - -Reference pages are ideal for outlining how things work in terse and clear terms. -Less concerned with telling a story or addressing a specific use case, they should give a comprehensive outline of what your documenting. - -## Further reading - -- Read [about reference](https://diataxis.fr/reference/) in the Diátaxis framework diff --git a/docs/starlight/src/content/docs/tech/ci.md b/docs/starlight/src/content/docs/tech/ci.md new file mode 100644 index 000000000..4b5c84dae --- /dev/null +++ b/docs/starlight/src/content/docs/tech/ci.md @@ -0,0 +1,19 @@ +--- +title: CI +description: Details on continuous integration +--- + +The aim is to have an ultra fast and simple CI. + +The CI is powerered by github acctions and the aims are: +1. Full CI run should only take 1 min for the entire monorepo. +2. CI costs should happily fit inside githubs free tier. That's 2000 minutes a month. However none of these minutes is currently used as runs that take under a minute don't seem to count towards this total. +3. Try and use some of the new generation of Rust based tools to keep every stage as fast as possible. + +[Dependabot](https://github.com/dependabot) is enabled on the repo and runs everyday. In general the number of dependencies is kept as low as possible. However the aim is to only have items updated on a weekly basis. + +[Sonarqube](https://sonarcloud.io/organizations/nigelbreslaw/projects) offers a free tier for public projects and runs as a quality gate on every PR. + +:::tip[Enterprise CI] +Self hosting a Gitlab runner would enable an even faster CI. Various installs and NPM packages would be auto cached. A higher end multicore VM could build, lint and test everything faster. Finally [Turborepo](https://turbo.build/) can be used to cache stages to avoid rebuilding and retesting unchanged projects in the monorepo. +::: diff --git a/docs/starlight/src/content/docs/tech/misc.md b/docs/starlight/src/content/docs/tech/misc.md new file mode 100644 index 000000000..e9896ae6c --- /dev/null +++ b/docs/starlight/src/content/docs/tech/misc.md @@ -0,0 +1,6 @@ +--- +title: Misc +description: Details on previous tech trials +--- + +December 2023: I did try to use [Bun](https://bun.sh/) which limits development to Linux and MacOS with Windows support only on [WSL](https://learn.microsoft.com/en-us/windows/wsl/about). However the monorepo and full node ecosystem support isn't quite there yet. Thus Node and [Pnpm](https://pnpm.io) are used instead. CI runs as of 25.12.2023 are ~25 seconds with PNPM and probably would be 5-8 seconds faster with Bun. I will revisit Bun later in 2024 when its compatibility and Monorepo support improves. \ No newline at end of file