[doc] Created toolversion pre-processor Signed-off-by: Hugo McNally <hugo.mcnally@gmail.com> Co-authored-by: Harry Callahan <hcallahan@lowrisc.org>
diff --git a/doc/guides/getting_started/book.toml b/doc/guides/getting_started/book.toml index e8c05b2..7bbc08b 100644 --- a/doc/guides/getting_started/book.toml +++ b/doc/guides/getting_started/book.toml
@@ -14,3 +14,6 @@ git-repository-url = "https://github.com/lowrisc/opentitan" edit-url-template = "https://github.com/lowrisc/opentitan/edit/master/doc/guides/getting_started/{path}" curly-quotes = true + +[preprocessor.toolversion] +command = "../../../util/mdbook_toolversion.py"
diff --git a/doc/guides/getting_started/src/README.md b/doc/guides/getting_started/src/README.md index fda574b..442f502 100644 --- a/doc/guides/getting_started/src/README.md +++ b/doc/guides/getting_started/src/README.md
@@ -197,7 +197,7 @@ The example below is for Ubuntu 20.04: ``` -export VERIBLE_VERSION={{< tool_version "verible" >}} +export VERIBLE_VERSION={{#tool-version verible }} wget https://github.com/google/verible/releases/download/${VERIBLE_VERSION}/verible-${VERIBLE_VERSION}-Ubuntu-20.04-focal-x86_64.tar.gz tar -xf verible-${VERIBLE_VERSION}-Ubuntu-20.04-focal-x86_64.tar.gz ``` @@ -205,7 +205,7 @@ If you are using Ubuntu 18.04 then instead use: ```console -export VERIBLE_VERSION={{< tool_version "verible" >}} +export VERIBLE_VERSION={{#tool-version verible }} wget https://github.com/google/verible/releases/download/${VERIBLE_VERSION}/verible-${VERIBLE_VERSION}-Ubuntu-18.04-bionic-x86_64.tar.gz tar -xf verible-${VERIBLE_VERSION}-Ubuntu-18.04-bionic-x86_64.tar.gz ``` @@ -219,7 +219,7 @@ After installation you need to add `/tools/verible/$VERIBLE_VERSION/bin` to your `PATH` environment variable. -Note that we currently use version {{< tool_version "verible" >}}, but it is expected that this version is going to be updated frequently, since the tool is under active development. +Note that we currently use version {{#tool-version verible }}, but it is expected that this version is going to be updated frequently, since the tool is under active development. ### Step 6b: Install OpenOCD (optional)
diff --git a/doc/guides/getting_started/src/install_vivado/README.md b/doc/guides/getting_started/src/install_vivado/README.md index db7ed0d..7533c6d 100644 --- a/doc/guides/getting_started/src/install_vivado/README.md +++ b/doc/guides/getting_started/src/install_vivado/README.md
@@ -11,13 +11,13 @@ ## Install Xilinx Vivado -_**Vivado Version:** The recommendation is to use Vivado {{< tool_version "vivado" >}}._ +_**Vivado Version:** The recommendation is to use Vivado {{#tool-version vivado }}._ Following the arrival of Vivado ML Edition, you will need to follow the links for that, eg. Products -> Hardware Development -> Vivado ML. -Then click on 'Vivado Archive' in the Version list and locate version {{< tool_version "vivado" >}} of Vivado Design Suite. +Then click on 'Vivado Archive' in the Version list and locate version {{#tool-version vivado }} of Vivado Design Suite. See [Download and -Installation](https://docs.xilinx.com/r/{{< tool_version "vivado" >}}-English/ug973-vivado-release-notes-install-license/Download-and-Installation) +Installation](https://docs.xilinx.com/r/{{#tool-version vivado }}-English/ug973-vivado-release-notes-install-license/Download-and-Installation) for installation instructions. When asked what edition to install, choose "Vivado HL Design Edition". @@ -28,7 +28,7 @@ After installing Vivado, you will need to add Vivado's paths to your shell environment. See [Launching the Vivado IDE from the Command Line on Windows or -Linux](https://docs.xilinx.com/r/{{< tool_version "vivado" >}}-English/ug892-vivado-design-flows-overview/Launching-the-Vivado-IDE-from-the-Command-Line-on-Windows-or-Linux) +Linux](https://docs.xilinx.com/r/{{#tool-version vivado }}-English/ug892-vivado-design-flows-overview/Launching-the-Vivado-IDE-from-the-Command-Line-on-Windows-or-Linux) for instructions. ## Device permissions: udev rules
diff --git a/doc/guides/getting_started/src/setup_fpga.md b/doc/guides/getting_started/src/setup_fpga.md index 5d6d113..118ab84 100644 --- a/doc/guides/getting_started/src/setup_fpga.md +++ b/doc/guides/getting_started/src/setup_fpga.md
@@ -86,7 +86,7 @@ To this end, run: ```console -. /tools/Xilinx/Vivado/{{< tool_version "vivado" >}}/settings64.sh +. /tools/Xilinx/Vivado/{{#tool-version vivado }}/settings64.sh cd $REPO_TOP make -C $(dirname $(find bazel-out/* -wholename '*synth-vivado/Makefile')) build-gui ``` @@ -111,7 +111,7 @@ You can then navigate to the created project directory, and open Vivado ```console -. /tools/Xilinx/Vivado/{{< tool_version "vivado" >}}/settings64.sh +. /tools/Xilinx/Vivado/{{#tool-version vivado }}/settings64.sh cd $REPO_TOP/build/lowrisc_systems_chip_earlgrey_cw310_0.1/synth-vivado/ vivado ```
diff --git a/doc/guides/getting_started/src/setup_verilator.md b/doc/guides/getting_started/src/setup_verilator.md index bc0368c..b7f9b8a 100644 --- a/doc/guides/getting_started/src/setup_verilator.md +++ b/doc/guides/getting_started/src/setup_verilator.md
@@ -17,7 +17,7 @@ The example below assumes gcc-11 and g++-11 are installed on the system. ```console -export VERILATOR_VERSION={{< tool_version "verilator" >}} +export VERILATOR_VERSION={{#tool-version verilator }} git clone https://github.com/verilator/verilator.git cd verilator
diff --git a/util/mdbook_toolversion.py b/util/mdbook_toolversion.py new file mode 100755 index 0000000..84c5399 --- /dev/null +++ b/util/mdbook_toolversion.py
@@ -0,0 +1,36 @@ +#!/usr/bin/env python3 +# Copyright lowRISC contributors. +# Licensed under the Apache License, Version 2.0, see LICENSE for details. +# SPDX-License-Identifier: Apache-2.0 +import json +import sys +import re + +from mdbook import utils as md_utils +import check_tool_requirements + +# We are looking to match on the following example strings +# {{#tool-version verible }} +TOOLVERSION_PATTERN = re.compile(r'\{\{#tool-version\s+(.+?)\s*\}\}') + + +def main() -> None: + md_utils.supports_html_only() + + tool_requirements = check_tool_requirements.read_tool_requirements() + + # load both the context and the book from stdin + context, book = json.load(sys.stdin) + + for chapter in md_utils.chapters(book["sections"]): + # Add in the minimum tool version + chapter['content'] = TOOLVERSION_PATTERN.sub( + repl=lambda m: tool_requirements.get(m.group(1)).min_version, + string=chapter['content']) + + # dump the book into stdout + print(json.dumps(book)) + + +if __name__ == "__main__": + main()