Generate documentation from the code with hdoc (#80)

The documentation is going to https://docs.hdoc.io/danakj/subspace/ at this time.

In the future, we could split the documentation generation into a separate CI action entirely.
Since it only requires CMake configure, not the full compilation, it would not be too costly to
do so. Then we can track doc-building success separately from compile/tests success.

Author: danakj

.github/workflows/ci.yml

@@ -1,6 +1,8 @@
 name: CI
 
-on: [push]
+on:
+  push:
+    branches: [hdoc]
 
 jobs:
   build:
@@ -114,8 +116,9 @@ jobs:
           execute_process(
             COMMAND cmake
               -S .
-              -B build
+              -B out
               -D CMAKE_BUILD_TYPE=${{ matrix.config.build_type }}
+              -D CMAKE_EXPORT_COMPILE_COMMANDS=1
               -G Ninja
               -D CMAKE_MAKE_PROGRAM=${ninja_program}
             RESULT_VARIABLE result
@@ -139,7 +142,7 @@ jobs:
           endif()
 
           execute_process(
-            COMMAND cmake --build build
+            COMMAND cmake --build out
             RESULT_VARIABLE result
           )
           if (NOT result EQUAL 0)
@@ -154,15 +157,22 @@ jobs:
 
           execute_process(
             COMMAND ctest -j ${N} --rerun-failed --output-on-failure
-            WORKING_DIRECTORY build
+            WORKING_DIRECTORY out
             RESULT_VARIABLE result
           )
           if (NOT result EQUAL 0)
             message(FATAL_ERROR "Running tests failed!")
           endif()
 
+      - name: Documentation
+        if: startsWith(matrix.config.cxx, 'g++')
+        uses: hdoc/hdoc-github-action@v2
+        with:
+          compile-commands-path: out/compile_commands.json
+          hdoc-api-key: ${{ secrets.HDOC_PROJECT_API_KEY }}
+
       - name: Install Strip
-        run: cmake --install build --prefix instdir --strip
+        run: cmake --install out --prefix instdir --strip
 
       - name: Pack
         working-directory: instdir

.hdoc.toml

@@ -0,0 +1,24 @@
+[project]
+name = "subspace"
+version = "0.0.1"
+
+# Optional, adding this will enable direct links from the documentation
+# to your source code.
+git_repo_url = "https://github.com/chromium/subspace/"
+git_default_branch = "main"
+
+[paths]
+compile_commands = "out/compile_commands.json"
+
+[pages]
+#homepage = "README.md"
+paths = [
+    "README.md",
+]
+
+[ignore]
+paths = [
+    "/third_party/",
+    "_unittest.cc",
+    "/__private/",
+]

README.md

@@ -7,6 +7,8 @@ Please don't use this library. This is an experiment and we don't yet know where
 it will take us. There will be breaking changes without warning, and there is no
 stable version.
 
+Documentation: https://docs.hdoc.io/danakj/subspace/
+
 # Copyright
 
 All source files must include this header: