[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)