From 8fc4fcff9ef9ad58a836e38567ffb7e8c2907c33 Mon Sep 17 00:00:00 2001 From: Luca Colagrande Date: Mon, 26 Aug 2024 17:53:12 +0200 Subject: [PATCH] docs: Set up Doxygen documentation --- .github/workflows/publish-docs.yml | 15 +++------------ .gitignore | 1 + Makefile | 19 ++++++++++++++++--- docs/.gitignore | 1 - docs/Doxyfile | 11 +++++++++++ docs/doxybook2.json | 13 ------------- docs/rm/snRuntime.md | 1 + mkdocs.yml | 8 +------- 8 files changed, 33 insertions(+), 36 deletions(-) delete mode 100644 docs/.gitignore create mode 100644 docs/Doxyfile delete mode 100644 docs/doxybook2.json create mode 100644 docs/rm/snRuntime.md diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index e98139f075..084c0f03a6 100644 --- a/.github/workflows/publish-docs.yml +++ b/.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 diff --git a/.gitignore b/.gitignore index 5f7019e128..320ef19479 100644 --- a/.gitignore +++ b/.gitignore @@ -18,6 +18,7 @@ gmon.out # Docs /site/ /docs/generated/ +/docs/doxygen/ # Installation directories /.venv/ diff --git a/Makefile b/Makefile index 2d89360e35..048b0e04f3 100644 --- a/Makefile +++ b/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 $< diff --git a/docs/.gitignore b/docs/.gitignore deleted file mode 100644 index e4d05d91a7..0000000000 --- a/docs/.gitignore +++ /dev/null @@ -1 +0,0 @@ -runtime diff --git a/docs/Doxyfile b/docs/Doxyfile new file mode 100644 index 0000000000..f9d60136b5 --- /dev/null +++ b/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)= \ No newline at end of file diff --git a/docs/doxybook2.json b/docs/doxybook2.json deleted file mode 100644 index 28d69396ec..0000000000 --- a/docs/doxybook2.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "baseUrl": "/snitch_cluster/runtime/", - "indexInFolders": true, - "linkSuffix": "/", - "indexClassesName": "index", - "indexFilesName": "index", - "indexGroupsName": "index", - "indexNamespacesName": "index", - "indexRelatedPagesName": "index", - "indexExamplesName": "index", - "mainPageInRoot": true, - "mainPageName": "index" -} diff --git a/docs/rm/snRuntime.md b/docs/rm/snRuntime.md new file mode 100644 index 0000000000..42eb97ef23 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 2ccad29a75..d13ad0eb18 100644 --- a/mkdocs.yml +++ b/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