From 08f87682f731070943db9fc69a3d652ce1a0863a Mon Sep 17 00:00:00 2001 From: Chris Banks Date: Tue, 5 Mar 2024 17:10:18 +0000 Subject: [PATCH] Update build/test instructions in README. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit There's no advantage to running devdocs inside govuk-docker. It's much easier and quicker — especially for external contributors — to run it directly using Bundler. Issue #4528 is an example of where the previous (overly complex) build/run instructions prevented an external contribution. --- README.md | 63 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 32 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index acf0c2c4bc0..5d17eb477a6 100644 --- a/README.md +++ b/README.md @@ -1,72 +1,73 @@ # GOV.UK Developer Docs -👉 https://docs.publishing.service.gov.uk +👉 https://docs.publishing.service.gov.uk/ This is a static site generated with Middleman, using [alphagov/tech-docs-template](https://github.com/alphagov/tech-docs-template). Some of the files (like the CSS, javascripts and layouts) are managed in the template and are not supposed to be modified here. Any project-specific Ruby code needs to go into `/app`. -## Technical documentation +## Build the app locally -You can use the [GOV.UK Docker environment](https://github.com/alphagov/govuk-docker) to run the application and its tests with all the necessary dependencies. Follow [the usage instructions](https://github.com/alphagov/govuk-docker#usage) to get started. - -**Use GOV.UK Docker to run any commands that follow.** +```sh +bundle install +``` -### Running the app +## Run the tests locally ``` -./startup.sh +bundle exec rake ``` -The docs include pages pulled from other GitHub repositories. By default, all these "proxy" pages are pulled when you start the app, which can lead to rate limit error. Using a GitHub API token avoids this. +## Run the app locally -[Create a GitHub auth token](https://github.com/settings/tokens/new) (the token doesn't need any permissions). +```sh +SKIP_PROXY_PAGES=true ./startup.sh +``` -Store the token in a `.env` file like this: +## Proxy pages -``` -GITHUB_TOKEN=somethingsomething -``` +The live docs site includes pages from other alphagov GitHub repositories. To test this locally, omit `SKIP_PROXY_PAGES=true` from the command above. -Alternatively, you can also disable proxy pages temporarily e.g. +The app downloads these "proxy pages" at startup and this can cause GitHub to rate limit your requests. You can pass a valid GitHub API token to the app to help avoid this: -``` -env SKIP_PROXY_PAGES=true ./startup.sh -``` +1. [Create a GitHub token](https://github.com/settings/tokens/new). The token doesn't need any scopes. -Disabling proxy pages means you'll get a "Not Found" error if you try to access them locally. +1. Store the token in a `.env` file: -### Testing the app + ```sh + GITHUB_TOKEN=somethingsomething + ``` -``` -bundle exec rake -``` +1. Start the application: -### Updating the template + ```sh + ./startup.sh + ``` -You can pull down the latest version of the Tech Docs template by running: +## Update to the latest Tech Docs template ```sh bin/update ``` -### Deployment +## Deployment + +We host GOV.UK Developer Docs as a static site on GitHub Pages. The [ci.yml] GitHub Actions workflow updates the site automatically: -This project is hosted on GitHub Pages. It is [redeployed hourly on weekdays][actions] -(to pick up changes to external docs) and whenever a PR is merged. +- when a PR is merged to the default branch +- on an hourly schedule, to pick up changes to docs included from other repos -As part of the deployment, we build a static set of pages to minimise the response time -and potential issues with remote API calls. +### Build the static site locally ```sh NO_CONTRACTS=true bundle exec middleman build ``` -This will create a bunch of static files in `/build`. +This will create a `build` directory containing a set of HTML files. ## Licence [MIT License](LICENCE) -[actions]: https://github.com/alphagov/govuk-developer-docs/blob/main/.github/workflows/ci.yml +[ci.yml]: /.github/workflows/ci.yml