mirror of https://github.com/grpc/grpc.io.git
Greatly simplify build and build instructions (#830)
This commit is contained in:
Patrice Chalin
GitHub
parent
e381e1d9d7
commit
0aefbcd092
50
Makefile
50
Makefile
|
|
@ -1,40 +1,20 @@
|
|||
DRAFT_ARGS = --buildDrafts --buildFuture
|
||||
BUILD_ARGS = --minify
|
||||
ifeq (draft, $(or $(findstring draft,$(HEAD)),$(findstring draft,$(BRANCH))))
|
||||
BUILD_ARGS += $(DRAFT_ARGS)
|
||||
HTMLTEST_DIR=tmp
|
||||
HTMLTEST?=htmltest # Specify as make arg if different
|
||||
# Use $(HTMLTEST) in PATH, if available; otherwise, we'll get a copy
|
||||
ifeq (, $(shell which $(HTMLTEST)))
|
||||
GET_LINK_CHECKER_IF_NEEDED=get-link-checker
|
||||
override HTMLTEST=$(HTMLTEST_DIR)/bin/htmltest
|
||||
endif
|
||||
|
||||
clean:
|
||||
rm -rf public/* resources
|
||||
check-internal-links: $(GET_LINK_CHECKER_IF_NEEDED)
|
||||
$(HTMLTEST)
|
||||
|
||||
serve:
|
||||
@./check_hugo.sh
|
||||
hugo serve
|
||||
check-all-links: $(GET_LINK_CHECKER_IF_NEEDED)
|
||||
$(HTMLTEST) --conf .htmltest.external.yml
|
||||
|
||||
serve-drafts:
|
||||
@./check_hugo.sh
|
||||
hugo serve $(DRAFT_ARGS)
|
||||
clean-htmltest-dir:
|
||||
rm -Rf $(HTMLTEST_DIR)
|
||||
|
||||
serve-production: clean
|
||||
@./check_hugo.sh
|
||||
hugo serve -e production --minify
|
||||
|
||||
production-build: clean
|
||||
@./check_hugo.sh
|
||||
hugo --minify
|
||||
|
||||
preview-build: clean
|
||||
@./check_hugo.sh
|
||||
hugo --baseURL $(DEPLOY_PRIME_URL) \
|
||||
-e development $(BUILD_ARGS)
|
||||
|
||||
link-checker-setup:
|
||||
curl https://raw.githubusercontent.com/wjdp/htmltest/master/godownloader.sh | bash
|
||||
|
||||
run-link-checker:
|
||||
bin/htmltest
|
||||
|
||||
check-internal-links: production-build link-checker-setup run-link-checker
|
||||
|
||||
check-all-links: production-build link-checker-setup
|
||||
bin/htmltest --conf .htmltest.external.yml
|
||||
get-link-checker:
|
||||
rm -Rf $(HTMLTEST_DIR)/bin
|
||||
curl https://htmltest.wjdp.uk | bash -s -- -b $(HTMLTEST_DIR)/bin
|
||||
|
|
|
|||
132
README.md
132
README.md
|
|
@ -4,59 +4,19 @@ The [grpc.io][] site, built using [Hugo][] and hosted on [Netlify][].
|
|||
|
||||
## Build prerequisites
|
||||
|
||||
### 1. Install the following tools
|
||||
To build and serve the site, you'll need the latest [LTS release][] of **Node**.
|
||||
Like Netlify, we use **[nvm][]**, the Node Version Manager, to install and
|
||||
manage Node versions:
|
||||
|
||||
- **[Hugo, extended edition][hugo-install]**; match the version specified in
|
||||
[netlify.toml](netlify.toml)
|
||||
- **Node**, the latest [LTS release][]. Like Netlify, we use **[nvm][]**, the
|
||||
Node Version Manager, to install and manage Node versions:
|
||||
```console
|
||||
$ nvm install --lts
|
||||
```
|
||||
|
||||
### 2. Clone this repo _and_ its submodules
|
||||
|
||||
> IMPORTANT: This repo has **recursive git _submodules_**, which affects how you
|
||||
> clone it.
|
||||
|
||||
The _simplest_ way to get a full copy of this repo is to clone the repo _and_
|
||||
its submodules _at the same time_ by running this command from a command shell /
|
||||
window:
|
||||
|
||||
```console
|
||||
$ git clone --recurse-submodules https://github.com/grpc/grpc.io.git
|
||||
```
|
||||
### 3. Change directories
|
||||
|
||||
From this point on you'll be working from the `grpc.io` directory:
|
||||
|
||||
```console
|
||||
$ cd grpc.io
|
||||
```
|
||||
### 4. Did you get the submodules?
|
||||
|
||||
Forgetting to clone the submodules is a common error.
|
||||
|
||||
If you forgot the `--recurse-submodules` option when you ran the `clone` command
|
||||
given in step 2 above or, if you cloned the repo using another method, as
|
||||
described in [Cloning a repository][], then you'll need to fetch the repo's
|
||||
submodules.
|
||||
|
||||
To (recursively) fetch the submodules, run the following command from the
|
||||
`grpc.io` directory:
|
||||
|
||||
```console
|
||||
$ git submodule update --init --recursive --depth 1
|
||||
```
|
||||
|
||||
> NOTE: Unsure if you've fetched the submodules? The Git command above is
|
||||
> idempotent, so you can safely (re-)run it -- if you already have the
|
||||
> submodules, it will have no effect.
|
||||
|
||||
### 5. Run installation scripts
|
||||
|
||||
Install NPM packages:
|
||||
## Setup
|
||||
|
||||
1. Clone or download a copy of this repo.
|
||||
2. From a terminal window, change to the cloned or unzipped repo directory.
|
||||
3. Get NPM packages and git submodules, including the the [Docsy][] theme:
|
||||
```console
|
||||
$ npm install
|
||||
```
|
||||
|
|
@ -66,86 +26,42 @@ $ npm install
|
|||
Run the following command to have Hugo generate the site files:
|
||||
|
||||
```console
|
||||
$ hugo
|
||||
$ npm run build
|
||||
```
|
||||
|
||||
The `public` folder contains the generated site.
|
||||
You'll find the generated site files in the `public` folder.
|
||||
|
||||
## Serve the site locally
|
||||
|
||||
To locally serve this site, use **one** of the following commands.
|
||||
|
||||
> **Note**: Hugo serves pages from memory by default, so if you want to
|
||||
> (re-)generate the website files to disk, use the build command above.
|
||||
|
||||
### a) Serve using [Hugo][] via `make`
|
||||
To locally serve the site at [localhost:8888][], run the following command:
|
||||
|
||||
```console
|
||||
$ make serve
|
||||
hugo server
|
||||
Start building sites …
|
||||
...
|
||||
Environment: "development"
|
||||
Serving pages from memory
|
||||
...
|
||||
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
|
||||
Press Ctrl+C to stop
|
||||
```
|
||||
|
||||
This generates _unminified_ site pages. Other [Makefile](Makefile) targets
|
||||
include the following:
|
||||
|
||||
- `serve-drafts` to also serve draft and future pages
|
||||
- `serve-production` to server files exactly as they'll appear in production
|
||||
|
||||
### b) Serve using Netlify dev
|
||||
|
||||
[Netlify dev][] uses Hugo under the hood to serve the site, but it also creates
|
||||
a proxy (at port 8888 by default), to handle [site redirects][]:
|
||||
|
||||
```console
|
||||
$ npx netlify dev
|
||||
```
|
||||
|
||||
If you also want to serve draft and future pages use this command:
|
||||
|
||||
```console
|
||||
$ npx netlify dev -c "hugo serve -DFw"
|
||||
$ npm run serve
|
||||
```
|
||||
|
||||
## Site deploys and PR previews
|
||||
|
||||
Commits to the `main` branch are _automatically_ published by [Netlify][]. You
|
||||
can see deploy logs and more from the [Netlify gRPC Team dashboard][], provided
|
||||
you have the necessary permissions.
|
||||
If you submit a PR, Netlify will automatically create a [deploy preview][] so
|
||||
that you can review your changes. Once your PR is merged, Netlify automcatically
|
||||
deploys to the production site [grpc.io][].
|
||||
|
||||
_PR previews_ are automatically built by [Netlify][] as well. By default, a PR
|
||||
preview is identical to a production build.
|
||||
> **Note**: PR previews include _draft pages_, but production builds do not.
|
||||
|
||||
If you want draft and future pages to also appear in a PR preview, then make
|
||||
sure that the word "draft" appears in the branch name used to create the PR.
|
||||
You can see deploy logs and more from the [Netlify gRPC Team dashboard][],
|
||||
provided you have the necessary permissions.
|
||||
|
||||
## Checking links
|
||||
## Contribute
|
||||
|
||||
You can check the site's internal links by running this command:
|
||||
We welcome issues and PRs! For details, see [Contribute][].
|
||||
|
||||
```console
|
||||
$ make check-internal-links
|
||||
```
|
||||
|
||||
This deletes the generated `public` directory, builds the "production" version
|
||||
of the site, and verifies that internal links are valid. Please note that
|
||||
internal links prefixed with `/grpc` do not work in your local environment
|
||||
(there are redirects applied by [Netlify](https://netlify.com)). Any errors
|
||||
returned from `/grpc` links are false negatives that you can ignore.
|
||||
|
||||
[Cloning a repository]: https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository
|
||||
[Contribute]: https://grpc.io/community/#contribute
|
||||
[deploy preview]: https://www.netlify.com/blog/2016/07/20/introducing-deploy-previews-in-netlify/
|
||||
[Docsy]: https://www.docsy.dev
|
||||
[grpc.io]: https://grpc.io
|
||||
[Hugo]: https://gohugo.io
|
||||
[hugo-install]: https://gohugo.io/getting-started/installing
|
||||
[localhost:8888]: http://localhost:8888
|
||||
[LTS release]: https://nodejs.org/en/about/releases/
|
||||
[Netlify]: https://netlify.com
|
||||
[Netlify dev]: https://www.netlify.com/products/dev
|
||||
[Netlify gRPC Team dashboard]: https://app.netlify.com/teams/grpc/overview
|
||||
[Netlify]: https://netlify.com
|
||||
[nvm]: https://github.com/nvm-sh/nvm/blob/master/README.md#installing-and-updating
|
||||
[site redirects]: layouts/index.redirects
|
||||
|
|
|
|||
|
|
@ -1,6 +0,0 @@
|
|||
#!/bin/bash
|
||||
|
||||
set -e
|
||||
|
||||
command -v hugo >/dev/null || (echo "Hugo extended must be installed on your system." >/dev/stderr; exit 1)
|
||||
hugo version | grep -i extended >/dev/null || (echo "Your Hugo installation does not appear to be extended." >/dev/stderr; exit 1)
|
||||
|
|
@ -1,12 +1,9 @@
|
|||
[build]
|
||||
publish = "public"
|
||||
command = "make production-build"
|
||||
|
||||
[build.environment]
|
||||
HUGO_VERSION = "0.82.0"
|
||||
command = "npm run build:production"
|
||||
|
||||
[context.branch-deploy]
|
||||
command = "make preview-build"
|
||||
command = "npm run build:preview"
|
||||
|
||||
[context.deploy-preview]
|
||||
command = "make preview-build"
|
||||
command = "npm run build:preview"
|
||||
|
|
|
|||
16
package.json
16
package.json
|
|
@ -1,11 +1,21 @@
|
|||
{
|
||||
"scripts": {
|
||||
"get-submodules": "git submodule update --init --recursive --depth 1",
|
||||
"preinstall": "npm run get-submodules"
|
||||
"_check-links": "make check-internal-links",
|
||||
"build:preview": "hugo --cleanDestinationDir -DFE --minify --baseURL \"${DEPLOY_PRIME_URL:-/}\"",
|
||||
"build:production": "hugo --cleanDestinationDir --minify",
|
||||
"build": "hugo --cleanDestinationDir -e dev -DFE",
|
||||
"check-links": "npm run _check-links",
|
||||
"postbuild:preview-DISABLED": "npm run _check-links",
|
||||
"precheck-links": "npm run build",
|
||||
"preinstall": "npm run submodule:get",
|
||||
"serve": "netlify dev -c \"hugo serve --minify -DFE -w\"",
|
||||
"submodule:get": "git submodule update --init --recursive --depth 1",
|
||||
"submodule:update": "git submodule update --remote --recursive --depth 1"
|
||||
},
|
||||
"devDependencies": {
|
||||
"autoprefixer": "^10.3.1",
|
||||
"netlify-cli": "^3.39.4",
|
||||
"hugo-extended": "0.82.0",
|
||||
"netlify-cli": "^6.6.1",
|
||||
"postcss": "^8.3.6",
|
||||
"postcss-cli": "^8.3.1"
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue