From 46e3c6b51e60bb48aea84a3d8743fb367cfa80e0 Mon Sep 17 00:00:00 2001 From: Peter Law Date: Sat, 2 Mar 2024 11:30:04 +0000 Subject: [PATCH 1/6] Regroup links to the footer --- README.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 122029fe..a2501eee 100644 --- a/README.md +++ b/README.md @@ -31,13 +31,14 @@ Once setup, the site will be accessible on http://localhost:4000/docs/ When you've made a change, either push it to a forked repository, or to a feature branch, and [raise a pull request][raise-a-pr]. -[clone-repo]: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository -[install-ruby]: https://www.ruby-lang.org/en/documentation/installation/ -[raise-a-pr]: https://github.com/srobo/docs/pull/new/main - ### Navigation Sidebar The docs navigation sidebar is generated from `_data/sidebar_tree.yaml` as part of the build process. This file is manually updated so that we can explicitly control which files are included, in what order as well as adjust the page titles. + + +[clone-repo]: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository +[install-ruby]: https://www.ruby-lang.org/en/documentation/installation/ +[raise-a-pr]: https://github.com/srobo/docs/pull/new/main From 63d9fcd305dd0328b5386417826366d579c912eb Mon Sep 17 00:00:00 2001 From: Peter Law Date: Sat, 2 Mar 2024 11:39:03 +0000 Subject: [PATCH 2/6] Explain how to check spellings locally --- README.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/README.md b/README.md index a2501eee..96a4176e 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,21 @@ Once setup, the site will be accessible on http://localhost:4000/docs/ When you've made a change, either push it to a forked repository, or to a feature branch, and [raise a pull request][raise-a-pr]. +### Spellings + +Spell checking is provided via [`cspell`][cspell], a library which integrates +with a number of code editors. Checking is run automatically on pull requests. + +If you're using VSCode, be sure to [install Code Spell Checker][vscode-cspell]. + +To run the checks manually (this is optional) you'll need to: + +0. install [NodeJS & `npm`][install-node] + +1. run `npm test` + +New spellings can be added to `.spelling`. Be sure to spell added words correctly! + ### Navigation Sidebar The docs navigation sidebar is generated from `_data/sidebar_tree.yaml` as part @@ -42,3 +57,6 @@ page titles. [clone-repo]: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository [install-ruby]: https://www.ruby-lang.org/en/documentation/installation/ [raise-a-pr]: https://github.com/srobo/docs/pull/new/main +[cspell]: https://cspell.org/ +[vscode-cspell]: https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker +[install-node]: https://downloads.nodesource.com/ From 037c810b8e05d18922cde3b1b0cd3e34cb5fadee Mon Sep 17 00:00:00 2001 From: Peter Law Date: Sat, 2 Mar 2024 11:39:52 +0000 Subject: [PATCH 3/6] Add missing link to where to view the site --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 96a4176e..1f068276 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,8 @@ Once setup, the site will be accessible on http://localhost:4000/docs/ $ rake dev ``` +4. View the website at + ## Making changes When you've made a change, either push it to a forked repository, or to a From 65e199a17a64476ba343e41ed2f03dc8341a7237 Mon Sep 17 00:00:00 2001 From: Peter Law Date: Sat, 2 Mar 2024 11:45:35 +0000 Subject: [PATCH 4/6] Clarify the nature of the Docker alternative and add links Importantly this pushes this option to being secondary and clarifies which of the build steps it replaces. Note that this also removes the instructions on how to use Docker. If users are not already familiar with Docker & Docker Compose then they are equally not equipped to judge the security posture that it presents. --- README.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 1f068276..6cda0ed9 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,6 @@ The Student Robotics public documentation. ## Getting Started -For ease of setup, a Docker container is provided. Install Docker and `docker-compose`, then run `docker compose up`. - -Once setup, the site will be accessible on http://localhost:4000/docs/ - -### Manual - 1. [Clone this repo][clone-repo] 1. [Install Ruby][install-ruby] @@ -28,6 +22,14 @@ Once setup, the site will be accessible on http://localhost:4000/docs/ 4. View the website at +### Docker + +If you would prefer to [install Docker][install-docker] and [Docker Compose][install-docker-compose] +rather than Ruby directly, these can be used instead. + +Note that this approach exposes the development server to the network you're +using, which may present a security risk. + ## Making changes When you've made a change, either push it to a forked repository, or to a @@ -58,6 +60,8 @@ page titles. [clone-repo]: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository [install-ruby]: https://www.ruby-lang.org/en/documentation/installation/ +[install-docker]: https://docs.docker.com/engine/install/ +[install-docker-compose]: https://docs.docker.com/compose/install/ [raise-a-pr]: https://github.com/srobo/docs/pull/new/main [cspell]: https://cspell.org/ [vscode-cspell]: https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker From 75c358e15d403aa791cec5f8fbb71647d8e1277d Mon Sep 17 00:00:00 2001 From: Peter Law Date: Sat, 2 Mar 2024 11:57:01 +0000 Subject: [PATCH 5/6] Un-number these points to avoid future diffs if things change --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 6cda0ed9..cd10a4df 100644 --- a/README.md +++ b/README.md @@ -8,19 +8,19 @@ The Student Robotics public documentation. 1. [Install Ruby][install-ruby] -2. Install Bundler (2.3 or above) and Rake +1. Install Bundler (2.3 or above) and Rake ``` shell $ gem install bundler rake ``` -3. Start the app in development mode +1. Start the app in development mode ```shell $ rake dev ``` -4. View the website at +1. View the website at ### Docker From 0aea5d8dacf651f25ab17df997c787eb763cc33e Mon Sep 17 00:00:00 2001 From: Peter Law Date: Sat, 2 Mar 2024 11:57:47 +0000 Subject: [PATCH 6/6] Expand the spellings section to cover all validation checks --- README.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index cd10a4df..ca85bc79 100644 --- a/README.md +++ b/README.md @@ -35,18 +35,25 @@ using, which may present a security risk. When you've made a change, either push it to a forked repository, or to a feature branch, and [raise a pull request][raise-a-pr]. -### Spellings +### Validation + +We have a number of checks which run against the docs to ensure they are ready +to publish, including internal links checks and spelling checks. Spell checking is provided via [`cspell`][cspell], a library which integrates with a number of code editors. Checking is run automatically on pull requests. -If you're using VSCode, be sure to [install Code Spell Checker][vscode-cspell]. +If you're using VSCode, be sure to install the [Code Spell Checker][vscode-cspell] +extension. -To run the checks manually (this is optional) you'll need to: +To run the checks manually (this is optional, but encouraged if making +non-trivial changes) you'll need to: 0. install [NodeJS & `npm`][install-node] -1. run `npm test` +1. run `npm install` (to install the spellings libraries) + +1. run `rake validate` to run all the checks New spellings can be added to `.spelling`. Be sure to spell added words correctly!