[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
