docs: Set up Doxygen documentation

.github/workflows/publish-docs.yml

@@ -24,18 +24,9 @@ jobs:
           version: 0.27.1
       - name: Install Python requirements
         run: pip install -r python-requirements.txt
-      - name: Generate runtime documentation
-        # yamllint disable rule:line-length
-        run: |
-          mkdir doxybook2; cd doxybook2
-          wget https://github.com/matusnovak/doxybook2/releases/download/v1.4.0/doxybook2-linux-amd64-v1.4.0.zip
-          unzip doxybook2-linux-amd64-v1.4.0.zip; cd ../
-          chmod +x doxybook2/bin/doxybook2
-          mkdir docs/runtime
-          ./doxybook2/bin/doxybook2 --input sw/doxygen/xml --output docs/runtime --config docs/doxybook2.json
-          rm -rf doxybook2
-        # yamllint enable rule:line-length
       - name: Generate documentation sources
-        run: make doc-srcs
+        run: |
+          make doc-srcs
+          make doxygen-docs
       - name: Build and deploy documentation
         run: mkdocs gh-deploy --force

.gitignore

@@ -18,6 +18,7 @@ gmon.out
 # Docs
 /site/
 /docs/generated/
+/docs/doxygen/
 
 # Installation directories
 /.venv/

Makefile

@@ -49,23 +49,36 @@ clean-nonfree:
 # Docs #
 ########
 
-GENERATED_DOCS_DIR = docs/generated
+DOCS_DIR = docs
+
+GENERATED_DOCS_DIR = $(DOCS_DIR)/generated
 GENERATED_DOC_SRCS = $(GENERATED_DOCS_DIR)/peripherals.md
 
+DOXYGEN_DOCS_DIR = $(DOCS_DIR)/doxygen
+DOXYGEN_INPUTS   = $(DOCS_DIR)/rm/snRuntime.md
+DOXYGEN_INPUTS  += $(shell find sw/snRuntime -name '*.c' -o -name '*.h')
+DOXYFILE         = $(DOCS_DIR)/Doxyfile
+
 all: docs
 clean: clean-docs
-.PHONY: doc-srcs docs clean-docs
+.PHONY: doc-srcs doxygen-docs docs clean-docs
 
 doc-srcs: $(GENERATED_DOC_SRCS)
 
-docs: doc-srcs
+doxygen-docs: $(DOXYGEN_DOCS_DIR)
+
+docs: doc-srcs doxygen-docs
 	mkdocs build
 
 clean-docs:
 	rm -rf $(GENERATED_DOCS_DIR)
+	rm -rf $(DOXYGEN_DOCS_DIR)
 
 $(GENERATED_DOCS_DIR):
 	mkdir -p $@
 
 $(GENERATED_DOCS_DIR)/peripherals.md: hw/snitch_cluster/src/snitch_cluster_peripheral/snitch_cluster_peripheral_reg.hjson | $(GENERATED_DOCS_DIR)
 	$(REGGEN) -d $< > $@
+
+$(DOXYGEN_DOCS_DIR): $(DOXYFILE) $(DOXYGEN_INPUTS)
+	doxygen $<

docs/Doxyfile

@@ -0,0 +1,11 @@
+PROJECT_NAME = "Snitch Runtime"
+INPUT = docs/rm/snRuntime.md sw/snRuntime
+RECURSIVE = YES
+FILE_PATTERNS = *.h *.c
+OUTPUT_DIRECTORY = docs/doxygen/
+USE_MDFILE_AS_MAINPAGE = docs/rm/snRuntime.md
+GENERATE_LATEX = NO
+ENABLE_PREPROCESSING = YES
+MACRO_EXPANSION = YES
+EXPAND_ONLY_PREDEF = YES
+PREDEFINED = __attribute__(x)=

docs/rm/snRuntime.md

@@ -0,0 +1 @@
+These pages host the documentation for the Snitch runtime, a set of runtime and library functions to make writing parallel and efficient C code for Snitch easier.

mkdocs.yml

@@ -77,11 +77,5 @@ nav:
           - Snitch Target Utilities:
               - run.py: rm/snitch_target_utils/run.md
               - build.py: rm/snitch_target_utils/build.md
-          - Snitch Runtime:
-              - Pages: runtime/Pages/index.md
-              - Files: runtime/Files/index.md
-              - Classes: runtime/Classes/index.md
-              - Examples: runtime/Examples/index.md
-              - Modules: runtime/Modules/index.md
-              - Namespaces: runtime/Namespaces/index.md
+          - Snitch Runtime: doxygen/html/index.html
   - Publications: publications.md