[doc] Updated documentation to reference the new build script.
Signed-off-by: Hugo McNally <hugo.mcnally@gmail.com>
diff --git a/ci/scripts/build-docs.sh b/ci/scripts/build-docs.sh
index 40885e6..e194ded 100755
--- a/ci/scripts/build-docs.sh
+++ b/ci/scripts/build-docs.sh
@@ -13,10 +13,10 @@
}
# Upload Doxygen Warnings if Present
-if [ -f "build/docs-generated/sw/doxygen_warnings.log" ]; then
+if [ -f "build-site/gen/doxygen_warnings.log" ]; then
echo -n "##vso[task.uploadfile]"
- echo "${PWD}/build/docs-generated/sw/doxygen_warnings.log"
+ echo "${PWD}/build-site/gen/doxygen_warnings.log"
# Doxygen currently generates lots of warnings.
# echo -n "##vso[task.issue type=warning]"
- # echo "Doxygen generated warnings. Use 'util/build_docs.py' to generate warning logfile."
+ # echo "Doxygen generated warnings. Use 'util/site/build-docs.sh' to generate warning logfile."
fi
diff --git a/doc/contributing/hw/methodology.md b/doc/contributing/hw/methodology.md
index 050c6dd..35fc9bd 100644
--- a/doc/contributing/hw/methodology.md
+++ b/doc/contributing/hw/methodology.md
@@ -44,10 +44,10 @@
The first is the [Hugo](https://gohugo.io) tool, which converts an annotated Markdown file into a rendered HTML file (including this document).
See the linked manual for information about the annotations and how to use it to create enhanced auto-generated additions to standard Markdown files.
-To automate the process a script [build_docs.py](../../guides/getting_started/src/build_docs.md) is provided for generating the documentation.
+To automate the process a script [build-docs.sh](https://opentitan.org/guides/getting_started/build_docs.html) is provided for generating the documentation.
The second is the [reggen](../../../util/reggen/README.md) register tool that helps define the methodology and description language for specifying hardware registers.
-These descriptions are used by `build_docs.py` to ensure that the technical specifications for the IP are accurate and up to date with the hardware being built.
+These descriptions are used by `build-docs.sh` to ensure that the technical specifications for the IP are accurate and up to date with the hardware being built.
Underlying and critical to this tooling is the human-written content that goes into the source Markdown and register descriptions.
Clarity and consistency is key.
diff --git a/doc/contributing/style_guides/markdown_usage_style.md b/doc/contributing/style_guides/markdown_usage_style.md
index 4931ed0..792d942 100644
--- a/doc/contributing/style_guides/markdown_usage_style.md
+++ b/doc/contributing/style_guides/markdown_usage_style.md
@@ -5,9 +5,9 @@
### Summary
Markdown files are used to write most documentation.
-The main Markdown tool is [Hugo](https://gohugo.io).
+The main Markdown tool is [mdbook](https://rust-lang.github.io/mdBook/).
-The Markdown processing is done using the `build_docs.py` tool in the `util` directory.
+There exists a script, `./util/site/build-docs.sh`, to build all `mdbook` books as well as run documentation generators such as `doxygen`.
As with all style guides the intention is to:
diff --git a/doc/guides/getting_started/src/build_docs.md b/doc/guides/getting_started/src/build_docs.md
index b882d0d..b26613b 100644
--- a/doc/guides/getting_started/src/build_docs.md
+++ b/doc/guides/getting_started/src/build_docs.md
@@ -1,23 +1,23 @@
# Building documentation
-The documentation for OpenTitan is available [online](https://docs.opentitan.org).
-The creation of documentation is mainly based around the conversion from Markdown to HTML files with [Hugo](https://gohugo.io/).
+The documentation for OpenTitan is available [online](https://opentitan.org).
+The creation of documentation is mainly based around the conversion from Markdown to HTML files with [mdbook](https://rust-lang.github.io/mdBook/).
Rules for how to write correct Markdown files can be found in the [reference manual](https://opentitan.org/book/doc/contributing/style_guides/markdown_usage_style.md).
## Building locally
-Before Hugo is executed a few project specific processing steps are necessary.
-These steps require the installation of the dependencies outlined in the following section.
-All processing steps as well as the invocation to Hugo are combined in the script `util/build_docs.py`.
+There are a few project specific [preprocessors](https://rust-lang.github.io/mdBook/format/configuration/preprocessors.html).
+These preprocessors require the installation of the dependencies outlined in the [previous section](README.md#step-2-install-package-manager-dependencies).
+`util/site/build-docs.sh` handles building all books in the repository and other auto-generated content, such as the API documentation generated by [Doxygen](https://www.doxygen.nl/).
### Running the server
In order to run a local instance of the documentation server run the following command from the root of the project repository.
-```console
-$ ./util/build_docs.py --preview
+```sh
+./util/site/build-docs.sh serve
```
-This will execute the preprocessing, fetch the correct Hugo version, build the documentation and finally start a local server.
+This will execute the preprocessing, build the documentation and finally start a local server.
The output will indicate at which address the local instance can be accessed.
-The default is [http://127.0.0.1:1313](http://127.0.0.1:1313).
+The default is [http://0.0.0.0:9000](http://0.0.0.0:9000).
diff --git a/util/dvsim/README.md b/util/dvsim/README.md
index b2143b6..28f74ee 100644
--- a/util/dvsim/README.md
+++ b/util/dvsim/README.md
@@ -272,24 +272,16 @@
```
### APIs for external tools
-The `util/build_docs.py` script invokes the testplanner utility functions directly to parse the Hjson testplan and insert an HTML table within the DV document.
+The `util/site/build-docs.sh` script invokes the testplanner utility functions directly to parse the Hjson testplan and insert an HTML table within the DV document.
This is done by invoking:
-```console
-$ ./util/build_docs.py --preview
-```
-The output for each testplan will be saved into `build/docs-generated`.
-For example the GPIO IP testplan is rendered into a table at `build/docs-generated/hw/ip/gpio/data/gpio_testplan.hjson.testplan`.
-The complete OpenTitan documentation is rendered locally at `https://localhost:1313`.
-The following snippet of code can be found in `util/build_docs.py`:
-```python
-from dvsim.Testplan import Testplan
-
- # hjson_testplan_path: a string pointing to the path to Hjson testplan
- testplan = Testplan(hjson_testplan_path)
- text = testplan.get_testplan_table("html")
+```sh
+./util/site/build-docs.sh serve
```
+The `util/mdbook_testplan.py` preprocessor renders any testplan present the `SUMMARY.md` into the documenation.
+The complete OpenTitan documentation is rendered locally at `https://0.0.0.0:9000`.
+
## Future work
* Allow DUT and its imported testplans to have the same testpoint name as long as they are in separate files.
* The list of written tests are appended from both files.
diff --git a/util/reggen/doc/setup_and_use.md b/util/reggen/doc/setup_and_use.md
index 8281b38..6c2d3a4 100644
--- a/util/reggen/doc/setup_and_use.md
+++ b/util/reggen/doc/setup_and_use.md
@@ -25,16 +25,15 @@
is documented by the tool itself.
The documentation can be generated by running the following commands:
-```console
-$ cd $REPO_TOP/util
-$ ./build_docs.py
+```sh
+$REPO_TOP/util/site/build-docs.sh
```
-Under the hood, the `build_docs.py` tool will automatically use the `reggen`
-tool to produce Markdown and processing that into HTML.
+
+Under the hood, one of the mdbook preprocessors (`./util/mdbook_reggen.py`) uses the `reggen` to generate register tables in the documentation.
### Examples using standalone regtool
-Normally for documentation the `build_docs.py` tool will automatically
+Normally for documentation the `mdbook_reggen.py` will automatically
use `reggen`. The script `regtool.py` provides a standalone way to run
`reggen`. See the
[register tool documentation](../README.md)
