Doxygen (#84)

* set up Doxygen

- `.gitignore`: ignore Doxygen output
- limit Doxygen search to relevant paths
- move extra `.md`s to docs/
- `Makefile`: add Doxygen target
- use as much SVG as possible for Doxygen diagrams
- alias @meme as an \xrefitem

* new github workflow: run doxygen and push to gh pages

.github/workflows/doxygen.yml

@@ -0,0 +1,23 @@
+name: run Doxygen to generate docs
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: generate docs
+      uses: mattnotmitt/doxygen-action@v1
+      with:
+        doxyfile-path: 'Doxyfile'
+        enable-latex: true
+    - name: deploy docs to github pages
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs/doxygen

.gitignore

@@ -9,6 +9,9 @@ build/
 *.dol
 vtable.lcf
 
+# Generated documentation
+docs/doxygen/
+
 # Temporary files
 *.swp
 *.dump

Makefile

@@ -57,6 +57,7 @@ CC      := $(WINE) tools/mwcc_compiler/$(MWCC_VERSION)/mwcceppc.exe
 LD      := $(WINE) tools/mwcc_compiler/$(MWCC_VERSION)/mwldeppc.exe
 ELF2DOL := tools/elf2dol
 PYTHON  := python3
+DOXYGEN := doxygen
 
 POSTPROC := tools/postprocess.py
 
@@ -95,8 +96,6 @@ ALL_DIRS := build $(BUILD_DIR) $(addprefix $(BUILD_DIR)/,$(SRC_DIRS) $(ASM_DIRS)
 dirs:
 	$(shell mkdir -p $(ALL_DIRS))
 
-.PHONY: dirs tools
-
 $(LDSCRIPT): ldscript.lcf
 	$(CPP) -MMD -MP -MT $@ -MF $@.d -I include/ -I . -DBUILD_DIR=$(BUILD_DIR) -o $@ $<
 
@@ -111,6 +110,9 @@ clean:
 tools:
 	$(MAKE) -C tools
 
+docs:
+	$(DOXYGEN) Doxyfile
+
 $(ELF): $(O_FILES) $(LDSCRIPT)
 	echo $(O_FILES) > build/o_files
 	$(LD) $(LDFLAGS) -o $@ -lcf $(LDSCRIPT) @build/o_files
@@ -131,3 +133,5 @@ $(BUILD_DIR)/%.o: %.cpp
 ### Debug Print ###
 
 print-% : ; $(info $* is a $(flavor $*) variable set to [$($*)]) @true
+
+.PHONY: default all dirs clean tools docs print-%

README.md

@@ -6,7 +6,7 @@ It builds the following DOL:
 
 main.dol - `sha1: 4997D93B9692620C40E90374A0F1DBF0E4889395`
 
-And will eventually build all the [RELs](./rels_sha1.md).
+And will eventually build all the [RELs](./docs/rels_sha1.md).
 
 ## Windows Prerequisites