ci: Update to catch documentation build errors

.github/workflows/ci.yml

@@ -19,11 +19,7 @@ jobs:
     steps:
       - uses: actions/checkout@v2
       - name: Build docs
-        run: |
-          make docs
-          if mkdocs build | grep -q "ERROR"; then
-            exit 1
-          fi
+        run: make docs
 
   ##############################################
   # Simulate SW on Snitch Cluster w/ Verilator #

.github/workflows/publish-docs.yml

@@ -35,7 +35,7 @@ jobs:
           ./doxybook2/bin/doxybook2 --input sw/doxygen/xml --output docs/runtime --config docs/doxybook2.json
           rm -rf doxybook2
         # yamllint enable rule:line-length
-      - name: Generate peripheral registers documentation
-        run: make docs
+      - name: Generate documentation sources
+        run: make doc-srcs
       - name: Build and deploy documentation
         run: mkdocs gh-deploy --force

.gitlab-ci.yml

@@ -30,10 +30,6 @@ before_script:
 docs:
   script:
     - make docs
-    - if mkdocs build | grep -q "ERROR"; then
-        exit 1
-      fi
-
 
 #################################
 # Build Snitch cluster software #

Makefile

@@ -1,24 +1,30 @@
 # Copyright 2023 ETH Zurich and University of Bologna.
-# Solderpad Hardware License, Version 0.51, see LICENSE for details.
-# SPDX-License-Identifier: SHL-0.51
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
 
 REGGEN = $(shell bender path register_interface)/vendor/lowrisc_opentitan/util/regtool.py
 
 GENERATED_DOCS_DIR = docs/generated
+GENERATED_DOC_SRCS = $(GENERATED_DOCS_DIR)/peripherals.md
 
-.PHONY: all docs
+.PHONY: all doc-srcs docs
 .PHONY: clean clean-docs
 
 all: docs
 clean: clean-docs
 
-docs: docs/generated/peripherals.md
+doc-srcs: $(GENERATED_DOC_SRCS)
+
+docs: doc-srcs
+	@if mkdocs build | grep -q "ERROR"; then \
+		exit 1; \
+	fi
 
 clean-docs:
 	rm -rf $(GENERATED_DOCS_DIR)
 
 $(GENERATED_DOCS_DIR):
 	mkdir -p $@
 
-docs/generated/peripherals.md: hw/snitch_cluster/src/snitch_cluster_peripheral/snitch_cluster_peripheral_reg.hjson | $(GENERATED_DOCS_DIR)
+$(GENERATED_DOCS_DIR)/peripherals.md: hw/snitch_cluster/src/snitch_cluster_peripheral/snitch_cluster_peripheral_reg.hjson | $(GENERATED_DOCS_DIR)
 	$(REGGEN) -d $< > $@

docs/ug/documentation.md

@@ -10,20 +10,11 @@ documentation, make sure you have the required dependencies installed:
 pip install -r docs/requirements.txt
 ```
 
-After everything is installed, you can build and serve a local copy by
+After everything is installed, you can build a static copy of the `html` documentation by
 executing (in the root directory):
 
 ```shell
-mkdocs serve
-```
-
-This opens a local webserver listening on
-[http://127.0.0.1:8000/](http://127.0.0.1:8000/).
-
-Alternatively, you can build a static copy of the `html` documentation:
-
-```shell
-mkdocs build
+make docs
 ```
 
 ## Organization