From 73283b389f3da429940130dbf0056633169e0735 Mon Sep 17 00:00:00 2001 From: Evan Anderson Date: Fri, 31 Jul 2020 16:04:42 -0700 Subject: [PATCH 1/8] Switch to static build to avoid errors on MacOS X, and make it easier to debug issues. --- scripts/localbuild.sh | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/scripts/localbuild.sh b/scripts/localbuild.sh index 3fa1c512..defa77bf 100755 --- a/scripts/localbuild.sh +++ b/scripts/localbuild.sh @@ -84,7 +84,8 @@ PRBUILD="false" # - Locally build a specific version from $FORK: # ./scripts/localbuild.sh -b branchname # -while getopts f:b:a: arg; do +SERVER="" +while getopts f:b:a:s arg; do case $arg in f) echo '--- BUILDING FROM ---' @@ -116,6 +117,9 @@ while getopts f:b:a: arg; do BUILDENVIRONMENT="production" BUILDSINGLEBRANCH="false" ;; + s) + echo 'Running hugo in server mode' + SERVER="server" esac done @@ -127,4 +131,11 @@ source scripts/processsourcefiles.sh # BUILD MARKDOWN # Start HUGO build -hugo server --baseURL "" --environment "$BUILDENVIRONMENT" +hugo $SERVER --baseURL "" --environment "$BUILDENVIRONMENT" + +if [ -z "$SERVER" ]; then + echo '' + echo '********** DONE! **********' + echo '' + echo 'Content built to files, open the content/en to view the docs.' +fi From 8023eeeb66d3f2f79ea1b0cea4035efb2d069efc Mon Sep 17 00:00:00 2001 From: Evan Anderson Date: Fri, 31 Jul 2020 16:12:27 -0700 Subject: [PATCH 2/8] Update DEVELOPMENT.md --- DEVELOPMENT.md | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index a64a1f60..2d61392c 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -39,13 +39,25 @@ ## Run locally -You should be able to run `./scripts/localbuild.sh` and see your changes to the -website and docs repo reflected. Note that the script **copies** the data from -`../docs`, so you'll need to re-run the script to get fresh docs changes to show -up on the local site. +You should be able to run `./scripts/localbuild.sh` to generate a copy of the +docs in the `public/` folder. Note that the build will replace relative +`.../index.html` links with `.../`, so when browsing the local copy, you may +need to click on `index.html` files to get where you need to go. -> @evankanderson is working on -> [fixing this](https://github.com/knative/website/issues/158) +If you want the old behavior of starting a local webserver, you can run +`./scripts/localbuild.sh -s`, but see the notes below on the tradeoff: + +There are two benefits to preferring to build statically: + +- It's easier to read or use tools on the output files, rather than needing to + fetch the HTML from the server. This is particularly useful when refactoring + the website or doing other complicated rendering. + +- It avoids an issue (see below) on Macs, where the default open FD limit is too + low for the number of `inotify` calls that hugo wants to keep open. + +Additionally, since the script _copies_ your `docs` repo, the live-reload is +substantilly less useful than re-running the build and using a fresh copy. ## On a Mac @@ -62,7 +74,7 @@ brew install gnu-sed PATH="/usr/local/opt/gnu-sed/libexec/gnubin:$PATH" ``` -### File Descriptors +### File Descriptors in "server mode" By default, MacOS permits a very small number of open FDs. This will manifest as: From 6a8ad5fe849796ad4e8961cc453976f53dc7638f Mon Sep 17 00:00:00 2001 From: Evan Anderson Date: Fri, 31 Jul 2020 16:12:27 -0700 Subject: [PATCH 3/8] Update DEVELOPMENT.md --- DEVELOPMENT.md | 26 +++++++++++++++++++------- scripts/localbuild.sh | 2 +- 2 files changed, 20 insertions(+), 8 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index a64a1f60..2d61392c 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -39,13 +39,25 @@ ## Run locally -You should be able to run `./scripts/localbuild.sh` and see your changes to the -website and docs repo reflected. Note that the script **copies** the data from -`../docs`, so you'll need to re-run the script to get fresh docs changes to show -up on the local site. +You should be able to run `./scripts/localbuild.sh` to generate a copy of the +docs in the `public/` folder. Note that the build will replace relative +`.../index.html` links with `.../`, so when browsing the local copy, you may +need to click on `index.html` files to get where you need to go. -> @evankanderson is working on -> [fixing this](https://github.com/knative/website/issues/158) +If you want the old behavior of starting a local webserver, you can run +`./scripts/localbuild.sh -s`, but see the notes below on the tradeoff: + +There are two benefits to preferring to build statically: + +- It's easier to read or use tools on the output files, rather than needing to + fetch the HTML from the server. This is particularly useful when refactoring + the website or doing other complicated rendering. + +- It avoids an issue (see below) on Macs, where the default open FD limit is too + low for the number of `inotify` calls that hugo wants to keep open. + +Additionally, since the script _copies_ your `docs` repo, the live-reload is +substantilly less useful than re-running the build and using a fresh copy. ## On a Mac @@ -62,7 +74,7 @@ brew install gnu-sed PATH="/usr/local/opt/gnu-sed/libexec/gnubin:$PATH" ``` -### File Descriptors +### File Descriptors in "server mode" By default, MacOS permits a very small number of open FDs. This will manifest as: diff --git a/scripts/localbuild.sh b/scripts/localbuild.sh index defa77bf..c170a8f5 100755 --- a/scripts/localbuild.sh +++ b/scripts/localbuild.sh @@ -137,5 +137,5 @@ if [ -z "$SERVER" ]; then echo '' echo '********** DONE! **********' echo '' - echo 'Content built to files, open the content/en to view the docs.' + echo 'Content built to files, open public/index.html to view the docs.' fi From f8a2994bec8b47bf970da46702fc469cc1c8b520 Mon Sep 17 00:00:00 2001 From: RichieEscarez Date: Fri, 7 Aug 2020 15:12:26 -0700 Subject: [PATCH 4/8] Elaborate on local testing options --- DEVELOPMENT.md | 88 +++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 69 insertions(+), 19 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 2d61392c..89423dd0 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -39,25 +39,75 @@ ## Run locally -You should be able to run `./scripts/localbuild.sh` to generate a copy of the -docs in the `public/` folder. Note that the build will replace relative -`.../index.html` links with `.../`, so when browsing the local copy, you may -need to click on `index.html` files to get where you need to go. - -If you want the old behavior of starting a local webserver, you can run -`./scripts/localbuild.sh -s`, but see the notes below on the tradeoff: - -There are two benefits to preferring to build statically: - -- It's easier to read or use tools on the output files, rather than needing to - fetch the HTML from the server. This is particularly useful when refactoring - the website or doing other complicated rendering. - -- It avoids an issue (see below) on Macs, where the default open FD limit is too - low for the number of `inotify` calls that hugo wants to keep open. - -Additionally, since the script _copies_ your `docs` repo, the live-reload is -substantilly less useful than re-running the build and using a fresh copy. +You can use `./scripts/localbuild.sh` to build and test files locally. +The script uses Hugo's build and server commands in addition to some Knative +specific file scripts that enables optimal user experience in GitHub +(ie. use README.md files, allows our site to use relative linking +(not +[`rel` or `relref`](https://gohugo.io/content-management/cross-references/#use-ref-and-relref)), +etc.) and also meets Hugo/Docsy static site generator +and template requirements (ie. _index.hmtl files, etc.) + +The two local docs build options: + +- Simple/static HTML file generation for viewing how your Markdown renders in HTML: + + Use this to generate a static build of the documentation site into HTML. This + uses Hugo's build command [`hugo`](https://gohugo.io/commands/hugo/). + + From your clone of knative/website, you run `./scripts/localbuild.sh`. + + All of the HTML files are built into the `public/` folder from where you can open, + view, and test how each file renders. + + Notes: + + - This method does not mirror how knative.dev is generated and therefore is + only recommened to for testing how your files reneder. That also means that link + checking might not be 100% accurate. Hugo builds relative links differently + (all links based on the site root vs relative to the file in which the link + resides - this is part of the Knative specific file processing that is done) + therefore some links will not work between the statically built HTML files. + For example, links like `.../index.html` are converted to `.../` for simplicity + (servers treat them as the same destination) but when you browsing a local HTML + file you need to open/click on the individual `index.html` files to get where you want + to go. + - This method does however make it easier to read or use local tools on the HTML build + output files (vs. fetching the HTML from the server). For example, it is useful for + refactoring/moving content and ensuring that complicated Markdown renders properly. + - Using this method also avoids the MacOs specific issue (see below), where the default + open FD limit exceeds the total number of `inotify` calls that Hugo wants to keep open. + +- Mimic how knative.dev is built and hosted: + + Use this option to locally build knative.dev. This uses Hugo's local server + command [`hugo server`](https://gohugo.io/commands/hugo_server/). + + From your clone of knative/website, you run `./scripts/localbuild.sh -s`. + + All of the HTML files are temporarily copied into the `content/en/` folder to allow + the Hugo server to locally host those files at the URL:port specified in your terminal. + + Notes: + + - This method provides the following local build and test build options: + - test your locally cloned files + - build and test other user's remote forks (ie. locally build their PRs) + - option to build only a specific branch or all branches (and also from any speicifed fork) + - fully functioning site links + - [See all command options in localbuild.sh](https://github.com/knative/website/blob/master/scripts/localbuild.sh) + - Hugo's live-reload is not completely utilized due to the requied Knative specific file processing + scripts (you need to rerun `./scripts/localbuild.sh -s` to rebuild and reprocess any changes that you + make to the files from within your local knative/docs clone directory). + + Alternatively, if you want to use Hugo's live-reload feature, you can make temporary + changes to the copied files within the `content/en/` folder, and then when satisfied, you must + copy those changes into the corresponding files of your knative/docs clone. + - Files in `content/en/` are overwritten with a new copy of your local files in your knative/docs + clone folder each time that you run this script. Note that the last set of built files remain + in `content/en/` for you to run local tools against but are overwritten each time that you rerun the script. + - Using this method causes the MacOs specific issue (see below), where the default + open FD limit exceeds the total number of `inotify` calls that the Hugo server wants to keep open. ## On a Mac From 7b1d774473e75a344d457bf14741bbec27107d5f Mon Sep 17 00:00:00 2001 From: RichieEscarez Date: Fri, 7 Aug 2020 15:15:33 -0700 Subject: [PATCH 5/8] Add a little more detail --- scripts/localbuild.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/localbuild.sh b/scripts/localbuild.sh index c170a8f5..492ad250 100755 --- a/scripts/localbuild.sh +++ b/scripts/localbuild.sh @@ -137,5 +137,5 @@ if [ -z "$SERVER" ]; then echo '' echo '********** DONE! **********' echo '' - echo 'Content built to files, open public/index.html to view the docs.' + echo 'Static HTML files output to public/. Open public/index.html to view these files.' fi From c59b9129963b8e11bdb3d91dd0863dd1ad5a8fa9 Mon Sep 17 00:00:00 2001 From: RichieEscarez Date: Fri, 7 Aug 2020 15:24:25 -0700 Subject: [PATCH 6/8] typos --- DEVELOPMENT.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 89423dd0..9238b58b 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -69,7 +69,7 @@ The two local docs build options: resides - this is part of the Knative specific file processing that is done) therefore some links will not work between the statically built HTML files. For example, links like `.../index.html` are converted to `.../` for simplicity - (servers treat them as the same destination) but when you browsing a local HTML + (servers treat them as the same destination) but when you are browsing a local HTML file you need to open/click on the individual `index.html` files to get where you want to go. - This method does however make it easier to read or use local tools on the HTML build @@ -92,11 +92,11 @@ The two local docs build options: - This method provides the following local build and test build options: - test your locally cloned files - - build and test other user's remote forks (ie. locally build their PRs) + - build and test other user's remote forks (ie. locally build their PRs `./scripts/build.sh -f repofork -b branchname -s) - option to build only a specific branch or all branches (and also from any speicifed fork) - fully functioning site links - [See all command options in localbuild.sh](https://github.com/knative/website/blob/master/scripts/localbuild.sh) - - Hugo's live-reload is not completely utilized due to the requied Knative specific file processing + - Hugo's live-reload is not completely utilized due to the required Knative specific file processing scripts (you need to rerun `./scripts/localbuild.sh -s` to rebuild and reprocess any changes that you make to the files from within your local knative/docs clone directory). From 23e83e38b04d4778800baea67211d0bc71c91173 Mon Sep 17 00:00:00 2001 From: RichieEscarez Date: Fri, 7 Aug 2020 15:27:04 -0700 Subject: [PATCH 7/8] update examples and add -s --- scripts/localbuild.sh | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/scripts/localbuild.sh b/scripts/localbuild.sh index 492ad250..2e66c451 100755 --- a/scripts/localbuild.sh +++ b/scripts/localbuild.sh @@ -61,28 +61,31 @@ PRBUILD="false" # # USAGE: Append the -f repofork and/or the -b branchname to the command. # Example: -# ./scripts/build.sh -f repofork -b branchname +# ./scripts/build.sh -f repofork -b branchname -s # # (2) Run a complete local build of the knative.dev site. Clones all the content # from knative/docs repo, including all branches. # # USAGE: Append the -a true to the command. # Example: -# ./scripts/build.sh -a true +# ./scripts/build.sh -a true -s # # # Examples: -# - Default local build: +# - Default local clone static HTML build: # ./scripts/localbuild.sh # +# - Local clone build with localhost server: +# ./scripts/localbuild.sh -s +# # - Clone all docs releases from knative/docs and then run local build: -# ./scripts/localbuild.sh -a true +# ./scripts/localbuild.sh -a true -s # # - Locally build content from specified fork and branch: -# ./scripts/localbuild.sh -f repofork -b branchname +# ./scripts/localbuild.sh -f repofork -b branchname -s # # - Locally build a specific version from $FORK: -# ./scripts/localbuild.sh -b branchname +# ./scripts/localbuild.sh -b branchname -s # SERVER="" while getopts f:b:a:s arg; do From 8ce84b45291177596db99a2faf86b871c15407b2 Mon Sep 17 00:00:00 2001 From: RichieEscarez Date: Fri, 7 Aug 2020 15:30:37 -0700 Subject: [PATCH 8/8] sorry, another typo --- DEVELOPMENT.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 9238b58b..114c9579 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -63,7 +63,7 @@ The two local docs build options: Notes: - This method does not mirror how knative.dev is generated and therefore is - only recommened to for testing how your files reneder. That also means that link + only recommened to for testing how your files render. That also means that link checking might not be 100% accurate. Hugo builds relative links differently (all links based on the site root vs relative to the file in which the link resides - this is part of the Knative specific file processing that is done)