[doc] Setup unified build for mdbook based docs There now exists a script `util/site/build-docs.sh`, which builds the complete site. Signed-off-by: Harry Callahan <hcallahan@lowrisc.org> Co-authored-by: Hugo McNally <hugo.mcnally@gmail.com> Co-authored-by: James Wainwright <james.wainwright@lowrisc.org>
diff --git a/.gitignore b/.gitignore index 5689e71..110b2e6 100644 --- a/.gitignore +++ b/.gitignore
@@ -90,3 +90,6 @@ # mdbook builds into `./book` directories, let's ignore them book + +# Hugo Lock +.hugo_build.lock
diff --git a/book.toml b/book.toml index 2e102a3..67a2a04 100644 --- a/book.toml +++ b/book.toml
@@ -50,6 +50,6 @@ [preprocessor.doxygen] command = "./util/mdbook_doxygen.py" -out-dir = "docs/" -html-out-dir = "doxy/" +out-dir = "build-site/gen" +html-out-dir = "gen/doxy" dif-src-py-regex = 'dif_\S*\.h'
diff --git a/site/docs/doxygen/footer.html b/site/doxygen/footer.html similarity index 100% rename from site/docs/doxygen/footer.html rename to site/doxygen/footer.html
diff --git a/site/docs/doxygen/header.html b/site/doxygen/header.html similarity index 100% rename from site/docs/doxygen/header.html rename to site/doxygen/header.html
diff --git a/site/docs/doxygen/layout.xml b/site/doxygen/layout.xml similarity index 100% rename from site/docs/doxygen/layout.xml rename to site/doxygen/layout.xml
diff --git a/site/docs/doxygen/main_page.md b/site/doxygen/main_page.md similarity index 100% rename from site/docs/doxygen/main_page.md rename to site/doxygen/main_page.md
diff --git a/site/landing/layouts/index.html b/site/landing/layouts/index.html index c562e60..5b98009 100644 --- a/site/landing/layouts/index.html +++ b/site/landing/layouts/index.html
@@ -38,7 +38,10 @@ <nav id="main-nav" class="main-nav" aria-label="Main"> <ul id="menu" class="main-nav__list"> <li class="main-nav__item"> - <a href="https://docs.opentitan.org">Documentation</a> + <a href="/book/doc/introduction.html">Documentation</a> + </li> + <li class="main-nav__item"> + <a href="/guides/getting_started">Getting Started</a> </li> <li class="main-nav__item"> <a href="#partners">Partners</a> @@ -312,7 +315,10 @@ <nav class="footer-nav" aria-label="Full"> <ul class="footer-nav__list"> <li class="footer-nav__item"> - <a href="https://docs.opentitan.org">Documentation</a> + <a href="/book/doc/introduction.html">Documentation</a> + </li> + <li class="footer-nav__item"> + <a href="/guides/getting_started">Getting Started</a> </li> <li class="footer-nav__item"> <a href="#partners">Partners</a>
diff --git a/util/doxygen/Doxyfile b/util/doxygen/Doxyfile index b601e8d..309c997 100644 --- a/util/doxygen/Doxyfile +++ b/util/doxygen/Doxyfile
@@ -46,7 +46,7 @@ FILE_VERSION_FILTER = "git -C '$(SRCTREE_TOP)' log --format='%h' -1 --" -LAYOUT_FILE = "$(SRCTREE_TOP)/site/docs/doxygen/layout.xml" +LAYOUT_FILE = "$(SRCTREE_TOP)/site/doxygen/layout.xml" #--------------------------------------------------------------------------- # Configuration options related to warning and progress messages @@ -62,9 +62,9 @@ # Absolute path using $(SRCTREE_TOP) INPUT = "$(SRCTREE_TOP)/sw" \ "$(SRCTREE_TOP)/hw/top_earlgrey/sw" \ - "$(SRCTREE_TOP)/site/docs/doxygen/main_page.md" + "$(SRCTREE_TOP)/site/doxygen/main_page.md" -USE_MDFILE_AS_MAINPAGE = "$(SRCTREE_TOP)/site/docs/doxygen/main_page.md" +USE_MDFILE_AS_MAINPAGE = "$(SRCTREE_TOP)/site/doxygen/main_page.md" FILE_PATTERNS = *.h \ *.c \ @@ -80,7 +80,7 @@ EXCLUDE_SYMLINKS = YES # Absolute path using $(SRCTREE_TOP) -IMAGE_PATH = "$(SRCTREE_TOP)/site/docs/doxygen" +IMAGE_PATH = "$(SRCTREE_TOP)/site/doxygen" #--------------------------------------------------------------------------- # Configuration options related to source browsing @@ -94,23 +94,17 @@ SOURCE_TOOLTIPS = NO #--------------------------------------------------------------------------- -# Configuration options related to the alphabetical class index -#--------------------------------------------------------------------------- - -COLS_IN_ALPHA_INDEX = 2 - -#--------------------------------------------------------------------------- # Configuration options related to the HTML output #--------------------------------------------------------------------------- GENERATE_HTML = YES # Relative to `OUTPUT_DIRECTORY` -HTML_OUTPUT = "public-api/sw/apis" +HTML_OUTPUT = "doxy/" # Absolute paths using $(SRCTREE_TOP) -HTML_HEADER = "$(SRCTREE_TOP)/site/docs/doxygen/header.html" -HTML_FOOTER = "$(SRCTREE_TOP)/site/docs/doxygen/footer.html" +HTML_HEADER = "$(SRCTREE_TOP)/site/doxygen/header.html" +HTML_FOOTER = "$(SRCTREE_TOP)/site/doxygen/footer.html" HTML_COLORSTYLE_HUE = 271 @@ -193,8 +187,6 @@ # Configuration options related to the dot tool #--------------------------------------------------------------------------- -CLASS_DIAGRAMS = NO - HAVE_DOT = NO CLASS_GRAPH = NO COLLABORATION_GRAPH = NO
diff --git a/util/mdbook_doxygen.py b/util/mdbook_doxygen.py index 06bad74..56f3014 100755 --- a/util/mdbook_doxygen.py +++ b/util/mdbook_doxygen.py
@@ -54,14 +54,9 @@ file_name = Path(src_path).name - # First calculate the path to the generated dif header, - # relative to the root of the project. This is the form ingested - # by the difgen library scripts. - rel_dif_h = (book_root / src_path).relative_to(SRCTREE_TOP) - buffer = io.StringIO() buffer.write(f"# {file_name}\n") - difgen.gen_listing_html(html_out_dir, combined_xml, str(rel_dif_h), + difgen.gen_listing_html(html_out_dir, combined_xml, str(book_root / src_path), buffer) buffer.write( "\n<details><summary>\nGenerated from <a href=\"{}\">{}</a></summary>\n"
diff --git a/util/site/build-docs.sh b/util/site/build-docs.sh new file mode 100755 index 0000000..e152f8d --- /dev/null +++ b/util/site/build-docs.sh
@@ -0,0 +1,179 @@ +#!/usr/bin/env bash +# Copyright lowRISC contributors. +# Licensed under the Apache License, Version 2.0, see LICENSE for details. +# SPDX-License-Identifier: Apache-2.0 + +set -e + +# Get the project directory from the location of this script +this_dir=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd ) +proj_root=$( realpath "${this_dir}/../.." ) +build_dir="${proj_root}/build-site" + +####### +# CLI # +####### +declare command="build" +# The following are only used for "command='serve-proxy'" ------------------------| +declare public_domain="" # (optional) The public-facing domain <-| +declare public_port="" # (optional)The port added to the public-facing domain <-| + +case "$1" in + "build"|"build-local"|"build-staging"|"serve"|"serve-proxy") + command="$1" + public_domain="${2}" + public_port="${3}" + ;; + "help"|*) + echo "USAGE: $0 <command> [public_domain] [public_port]" + echo "" + echo "commands:" + echo " help prints this message." + echo " build build the site and docs for prod" + echo " build-local build the site and docs for a localhost server" + echo " build-staging build the site and docs for staging.opentitan.org" + echo " serve build and serve the site locally" + echo " serve-proxy build and serve the site, with a public url" + echo "" + echo "Optional arguments [public_domain] and [public_port] are only used when command='serve-proxy'" + exit 0 + ;; +esac + +################ +# DEPENDENCIES # +################ + +checkDeps () { + # Check for mdbook dep + if ! command -v mdbook >/dev/null; then + echo "E: mdbook not found, please install from your package manager or with:" >&2 + echo "E: $ cargo install mdbook" >&2 + exit 1 + fi + + # Check for hugo dep + if ! command -v hugo >/dev/null; then + echo "E: hugo not found, please install from your package manager" >&2 + exit 1 + fi +} +checkDeps + +################# +# CONFIGURATION # +################# +declare base_url +declare serve_port # The port used by the local webserver (using "build-docs.sh serve/serve-proxy") + +getURLs () { + # Defaults here are for production ("build-docs.sh build") + local scheme="https" + local domain="opentitan.org" + local port="" + + # Use un-encrypted localhost URLs when building/serving locally + # - serve on port 9000. + if [ "$command" = "build-local" ] || \ + [ "$command" = "serve" ]; then + scheme="http" + domain="localhost" + port=":9000" + serve_port=":9000" + fi + # "serve-proxy" gives us some simple defaults for serving behind a proxy: + # - set the public_domain/public_port appropriately (see $2/$3) + # - serve on port 8000. + if [ "$command" = "serve-proxy" ] ; then + scheme="http" + domain="${public_domain}" + port=":${public_port}" + serve_port=":8000" + fi + if [ "$command" = "build-staging" ] ; then + scheme="https" + domain="staging.opentitan.org" + fi + + base_url="${scheme}://${domain}${port}" +} +getURLs + +# Export some environment variables that tools will pick up +export HUGO_PARAMS_DOCSURL="${base_url}/book" # hugo +export URL_ROOT="${base_url}/book" # earlgrey_diagram + +# Build up doxygen command +doxygen_env="env" +doxygen_env+=" SRCTREE_TOP=${proj_root}" +doxygen_env+=" DOXYGEN_OUT=${build_dir}/gen" +doxygen_args="${proj_root}/util/doxygen/Doxyfile" + +# Build up mdbook arguments +mdbook_args="build" +mdbook_args+=" --dest-dir ${build_dir}/book/" +mdbook_args+=" ${proj_root}" + +mdbook_guides_args="build" +mdbook_guides_args+=" --dest-dir ${build_dir}/guides/getting_started" +mdbook_guides_args+=" ${proj_root}/doc/guides/getting_started" + +# Register the pre-processors +# Each book should only be passed the preprocessors it specifies inside the book.toml +# ./book.toml +book_env="env" +book_env+=" MDBOOK_PREPROCESSOR__TESTPLAN__COMMAND=${proj_root}/util/mdbook_testplan.py" +book_env+=" MDBOOK_PREPROCESSOR__OTBN__COMMAND=${proj_root}/util/mdbook_otbn.py" +book_env+=" MDBOOK_PREPROCESSOR__DOXYGEN__COMMAND=${proj_root}/util/mdbook_doxygen.py" +book_env+=" MDBOOK_PREPROCESSOR__REGGEN__COMMAND=${proj_root}/util/mdbook_reggen.py" +book_env+=" MDBOOK_PREPROCESSOR__WAVEJSON__COMMAND=${proj_root}/util/mdbook_wavejson.py" +book_env+=" MDBOOK_PREPROCESSOR__README2INDEX__COMMAND=${proj_root}/util/mdbook_readme2index.py" +book_env+=" MDBOOK_PREPROCESSOR__DASHBOARD__COMMAND=${proj_root}/util/mdbook_dashboard.py" +# ./doc/guides/getting_started/book.toml +book_guides_env="env" +book_guides_env+=" MDBOOK_PREPROCESSOR__TOOLVERSION__COMMAND=${proj_root}/util/mdbook_toolversion.py" + +# Build up Hugo arguments +hugo_args="" +hugo_args+=" --source ${proj_root}/site/landing/" +hugo_args+=" --destination ${build_dir}/" +hugo_args+=" --baseURL ${base_url}" + +############ +# BUILDING # +############ + +buildSite () { + mkdir -p "${build_dir}" + mkdir -p "${build_dir}/gen/doxy" + + echo "Building doxygen..." + pushd "${this_dir}" >/dev/null + # shellcheck disable=SC2086 + ${doxygen_env} doxygen ${doxygen_args} + popd >/dev/null + echo "Doxygen build complete." + + # shellcheck disable=SC2086 + ${book_env} mdbook ${mdbook_args} + # shellcheck disable=SC2086 + ${book_guides_env} mdbook ${mdbook_guides_args} + # shellcheck disable=SC2086 + hugo ${hugo_args} +} +buildSite + +########### +# SERVING # +########### + +# If serving, run the python HTTP server +if [ "$command" = "serve" ] || [ "$command" = "serve-proxy" ]; then + echo "--------------------------------------------" + echo + echo "Website being served at : ${base_url}" + echo + echo "--------------------------------------------" + python3 -m http.server -d "$build_dir" ${serve_port:1} + # strip leading : +fi
diff --git a/site/docs/README.md b/util/site/site-builder/README.md similarity index 76% rename from site/docs/README.md rename to util/site/site-builder/README.md index fdec017..3480ba7 100644 --- a/site/docs/README.md +++ b/util/site/site-builder/README.md
@@ -11,16 +11,13 @@ minutes to around twenty seconds. To rebuild and deploy the image use the `deploy-builder.sh` script. -# Update Hugo version - -The Hugo version is defined by variable `HUGO_EXTENDED_VERSION` in `util/build_docs.py`. -To ensure syntax highlighting is working correctly the CSS stylesheet must be updated following a version update. +# Appendix ## Update CSS stylesheet -Setting the option `noClasses = false` for `[markup.highlight]` in `site/docs/config.toml` requires a stylesheet to be available. +Setting the option `noClasses = false` for `[markup.highlight]` in `site/landing/config.toml` requires a stylesheet to be available. This option is used in order to have two styles for light and dark mode of the documentation site. -The stylesheet is stored in `site/docs/assets/scss/_chroma.scss`. +The stylesheet is stored in `site/landing/assets/scss/_chroma.scss`. Update the style if the Hugo version is changed: - Replace the content of `[data-user-color-scheme='light']` with the output of `hugo gen chromastyles --style=colorful`, but keep the first line containing the setting of the background.
diff --git a/site/docs/builder.Dockerfile b/util/site/site-builder/builder.Dockerfile similarity index 79% rename from site/docs/builder.Dockerfile rename to util/site/site-builder/builder.Dockerfile index c00d8ab..9c53f73 100644 --- a/site/docs/builder.Dockerfile +++ b/util/site/site-builder/builder.Dockerfile
@@ -5,8 +5,10 @@ FROM ubuntu:18.04 RUN apt-get update && \ - apt-get install -y locales locales-all git curl doxygen python3 python3-pip xsltproc && \ - apt-get clean; rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* /usr/share/doc/* + apt-get install -y \ + locales locales-all git curl doxygen python3 python3-pip xsltproc && \ + apt-get clean && \ + rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* /usr/share/doc/* ENV LC_ALL en_US.UTF-8 ENV LANG en_US.UTF-8
diff --git a/site/docs/cloudbuild-deploy-docs.yaml b/util/site/site-builder/cloudbuild-deploy-docs.yaml similarity index 100% rename from site/docs/cloudbuild-deploy-docs.yaml rename to util/site/site-builder/cloudbuild-deploy-docs.yaml
diff --git a/site/docs/deploy-builder.sh b/util/site/site-builder/deploy-builder.sh similarity index 100% rename from site/docs/deploy-builder.sh rename to util/site/site-builder/deploy-builder.sh