From 0b7bcb1c74680c07d6680e097e9ddf126a5b8732 Mon Sep 17 00:00:00 2001 From: John Bartholomew Date: Fri, 22 Mar 2024 17:40:41 +0000 Subject: [PATCH] refresh the instructions for building the docs Various minor changes: - gitignore the Jekyll output directory even if you run Jekyll from the repo root. - gitignore the WASM file since it's a build output. - Get rid of tools/scripts/serve_docs.sh - it's no longer needed since Jekyll 4.3.0 which fixed the Content-Type for WASM files (https://github.com/jekyll/jekyll/pull/8965) 4.3.0 was released October 2020. - In push_docs, when checking out the repo to the working directory, directly check out the gh-pages branch instead of checking out HEAD and then switching branch. - Update instructions accordingly. --- .gitignore | 3 ++ README.md | 18 ++++++------ release_checklist.md | 8 +++--- tools/scripts/push_docs.sh | 4 +-- tools/scripts/serve_docs.sh | 57 ------------------------------------- 5 files changed, 17 insertions(+), 73 deletions(-) delete mode 100755 tools/scripts/serve_docs.sh diff --git a/.gitignore b/.gitignore index 8d4b5d20e..defc809de 100644 --- a/.gitignore +++ b/.gitignore @@ -36,6 +36,9 @@ bazel-* /dist/ /jsonnet.egg-info/ /doc/.jekyll-cache/ +/production/ +/doc/production/ +/doc/js/libjsonnet.wasm # Cmake **/CMakeCache.txt diff --git a/README.md b/README.md index ea67d010f..1740fd0a4 100644 --- a/README.md +++ b/README.md @@ -157,19 +157,19 @@ Or you can build it yourself, which requires checking out [go-jsonnet](https://github.com/google/go-jsonnet). See the README.md in that repo for instructions. -Then, from the root of the repository you can generate and serve the website using -[Jekyll](https://jekyllrb.com/): +The standard library is documented in a structured format in `doc/_stdlib_gen/stdlib-content.jsonnet`. +The HTML (input for Jekyll) is regenerated using the following command: ``` -tools/scripts/serve_docs.sh +tools/scripts/update_web_content.sh ``` -This should the website on localhost:8200, automatically rebuild when you change any underlying -files, and automatically refresh your browser when that happens. - -The standard library is documented in a structured format in `doc/_stdlib_gen/stdlib-content.jsonnet`. -The HTML (input for Jekyll) is regenerated using the following command: +Then, from the root of the repository you can generate and serve the website using +[Jekyll](https://jekyllrb.com/) (you need version 4.3.0 or later): ``` -tools/scripts/update_web_content.sh +jekyll serve -s doc/ ``` + +This should build and serve the website locally, and automatically rebuild +when you change any underlying files. diff --git a/release_checklist.md b/release_checklist.md index 968b38ea7..1876f055c 100644 --- a/release_checklist.md +++ b/release_checklist.md @@ -35,8 +35,8 @@ Before doing the release, make sure that the project is in good state: * Make sure that the stdlib documentation is complete. Check the release notes for any additions or changes to stdlib and make sure they are reflected in the documentation. * Make sure that you can build the website locally. - * `make doc/js/libjsonnet.js` - * `tools/scripts/serve_docs.sh` + * Download or build libjsonnet.wasm (see README.md for instructions) + * `jekyll serve -s doc/` (you need Jekyll 4.3.0 or later) to serve the site locally to check it. * Check that it works in two different browsers. Make sure that live evaluation in the tutorial works. @@ -98,8 +98,8 @@ in one sitting and fix any unexpected problems. ## Update the website In google/jsonnet: -* `make doc/js/libjsonnet.js` -* `tools/scripts/serve_docs.sh` +* Build or download libjsonnet.wasm (see README.md) +* `jekyll serve -s docs/` * Check that the local version works in two different browsers. Make sure that live evaluation in the tutorial works. * `tools/scripts/push_docs.sh` * Check that the public works in two different browsers. Make sure that you are getting the new version (and not an old cached version). Make sure that live evaluation in the tutorial works. diff --git a/tools/scripts/push_docs.sh b/tools/scripts/push_docs.sh index 56d813cd5..51a14cdc4 100755 --- a/tools/scripts/push_docs.sh +++ b/tools/scripts/push_docs.sh @@ -56,7 +56,7 @@ if [ -z "$working_dir" ]; then trap "rm -rf ${working_dir}" EXIT fi -git clone $JSONNET_REPO "$working_dir" +git clone -b gh-pages $JSONNET_REPO "$working_dir" ( cd "$working_dir" @@ -74,5 +74,3 @@ jekyll build -d "$working_dir" git commit -am "Update docs." git push -u origin gh-pages ) - - diff --git a/tools/scripts/serve_docs.sh b/tools/scripts/serve_docs.sh deleted file mode 100755 index 7ca66e1c7..000000000 --- a/tools/scripts/serve_docs.sh +++ /dev/null @@ -1,57 +0,0 @@ -#!/usr/bin/env bash -# Copyright 2015 Google Inc. All rights reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -# Brings up the Jsonnet website locally. - -set -e - -function check { - which $1 > /dev/null || (echo "$1 not installed. Please install $1."; exit 1) -} - - -check jekyll - -if [ ! -r 'doc/_config.yml' ]; then -echo 'No doc/_config.yml file found.' >&1 -echo 'Are you running this script from the root of the Jsonnet repository?' >&1 -exit 1 -fi - -cd doc -#jekyll server --port 8200 --watch -cat << EOF -Jekyll currently does not support wasm in local serving mode due to an -erroneous content-type, so as a workaround we are just /building/ the site -with jekyll. To serve the built site, please change to the -doc/production directory and run a Python HTTP server like this: - -python3 -c 'import http.server -class Handler(http.server.SimpleHTTPRequestHandler): - def end_headers(self): - self.send_header("Cache-Control", "no-cache, no-store, must-revalidate") - self.send_header("Pragma", "no-cache") - self.send_header("Expires", "0") - http.server.SimpleHTTPRequestHandler.end_headers(self) - - -http.server.test(HandlerClass=Handler,port=8200) -' - -The site should then be accessible on localhost:8200 as normal. - -Running jekyll build --watch now... -EOF -jekyll build --watch