From ac1674521f6c32b515fdb437cafb41a54284dff7 Mon Sep 17 00:00:00 2001 From: Luca Colagrande Date: Thu, 7 Sep 2023 17:48:37 +0200 Subject: [PATCH] ci: Update to catch documentation build errors --- .github/workflows/ci.yml | 6 +----- .github/workflows/publish-docs.yml | 4 ++-- .gitlab-ci.yml | 4 ---- Makefile | 16 +++++++++++----- docs/ug/documentation.md | 13 ++----------- 5 files changed, 16 insertions(+), 27 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5b059ee67c..870de61041 100644 --- a/.github/workflows/ci.yml +++ b/.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 # diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index 78435cf0f1..188512ec6b 100644 --- a/.github/workflows/publish-docs.yml +++ b/.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 diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 9559135282..7368716c37 100644 --- a/.gitlab-ci.yml +++ b/.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 # diff --git a/Makefile b/Makefile index 4025fc0c32..06a1c662fc 100644 --- a/Makefile +++ b/Makefile @@ -1,18 +1,24 @@ # 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) @@ -20,5 +26,5 @@ clean-docs: $(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 $< > $@ diff --git a/docs/ug/documentation.md b/docs/ug/documentation.md index b1179e70e5..de61ab105b 100644 --- a/docs/ug/documentation.md +++ b/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