docs: Add support for generating a documentation site through Doxygen.

.github/workflows/docs.yaml

@@ -0,0 +1,46 @@
+name: "docs"
+
+on:
+  pull_request:
+  push:
+  schedule:
+    # Run daily at 00:15 UTC (the 15 is to avoid periods of high load)
+    - cron: "15 0 * * *"
+  workflow_dispatch:
+
+concurrency:
+  group: "${{github.workflow}}-${{github.ref}}"
+
+  # Cancel in-progress jobs for efficiency
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: "Build docs site"
+    runs-on: "ubuntu-latest"
+    steps:
+      - uses: "actions/checkout@v4"
+        with:
+          lfs: "true"
+          submodules: "recursive"
+
+      - name: "Install task"
+        shell: "bash"
+        run: "npm install -g @go-task/cli"
+
+      - name: "Build docs"
+        shell: "bash"
+        run: "task docs:site"
+
+      # Upload the built docs site if we need to debug any issues
+      - if: >-
+          contains(fromJSON('["push", "workflow_dispatch"]'), github.event_name)
+          && ('refs/heads/main' == github.ref || startsWith(github.ref, 'refs/tags/v'))
+        uses: "actions/upload-artifact@v4"
+        with:
+          name: "docs-html"
+          path: "build/docs/html"
+          if-no-files-found: "error"
+
+          # Retain the artifact for a week
+          retention-days: 7

README.md

@@ -109,13 +109,34 @@ To build the debug version:
 task build:debug
 ```
 
-## Documentation and examples
+## Examples
+
+[examples](examples) contains programs demonstrating usage of the library.
+See [examples/README.md](examples/README.md) for information on building and running the examples.
+
+## Documentation
 
 * [docs](docs) contains more detailed documentation including:
   * The [schema specification](docs/schema.md), which describes the syntax for
     writing your own schema
   * `log-surgeon`'s [design objectives](docs/design-objectives.md)
-* [examples](examples) contains programs demonstrating usage of the library.
+
+### Documentation site
+
+You can generate a documentation site that is useful for exploring functionality and test coverage.
+In particular, this documents all unit-tests, with additional detail for API-level tests.
+
+#### Commands
+
+To generate and view the files:
+
+* Run `task docs:site`.
+* Open `build/docs/html/index.html` in your preferred browser.
+
+To host the site locally and view it:
+
+* Run `task docs:serve`.
+* Open the URL and port output from the `serve` task in your preferred browser.
 
 ## Testing
 

docs/doxygen/Doxyfile

@@ -0,0 +1,25 @@
+# Project Information
+PROJECT_BRIEF = "Test coverage and internal documentation"
+PROJECT_NAME = "Log Surgeon"
+OUTPUT_DIRECTORY = build/docs/
+
+# Input
+INPUT = \
+    docs/doxygen/mainpage.dox \
+    tests/
+RECURSIVE = YES
+
+# Source Code Parsing
+EXTRACT_ALL = YES
+EXTRACT_PRIVATE = YES
+EXTRACT_STATIC = YES
+MACRO_EXPANSION = YES
+PREDEFINED = "TEST_CASE(x,y)=void x()"
+
+# Output
+GENERATE_LATEX = NO
+HTML_DYNAMIC_SECTIONS = YES
+TIMESTAMP = YES
+
+# Misc
+WARN_AS_ERROR = YES

docs/doxygen/mainpage.dox

@@ -0,0 +1,20 @@
+/** @mainpage
+ *
+ * # Use case examples of schema rules and parsing results:
+ *
+ * - @ref test_buffer_parser_no_capture "Use basic log parser"
+ * - @ref test_buffer_parser_capture "Use captures"
+ * - @ref test_buffer_parser_default_schema "Default CLP schema"
+ * - @ref test_buffer_parser_delimited_variables "Backtracking on delimited variables"
+ * - @ref test_buffer_parser_newline_vars "Identifying variables at the start of a line"
+ *
+ * # Unit-tests:
+ *
+ * - @ref unit_tests_capture "Capture"
+ * - @ref unit_tests_dfa "DFA"
+ * - @ref unit_tests_nfa "NFA"
+ * - @ref unit_tests_prefix_tree "Prefix tree"
+ * - @ref unit_tests_regex_ast "Regex AST"
+ * - @ref unit_tests_register_handler "Register handler"
+ * - @ref unit_tests_schema "Schema"
+ */

taskfile.yaml

@@ -6,6 +6,7 @@ shopt: ["globstar"]
 includes:
   build: "taskfiles/build.yaml"
   deps: "taskfiles/deps.yaml"
+  docs: "taskfiles/docs.yaml"
   lint: "taskfiles/lint.yaml"
   test: "taskfiles/test.yaml"
 

taskfiles/docs.yaml

@@ -0,0 +1,98 @@
+version: "3"
+
+includes:
+  utils:
+    internal: true
+    taskfile: "../tools/yscope-dev-utils/exports/taskfiles/utils/utils.yaml"
+
+vars:
+  # General paths
+  G_DOCS_BUILD_DIR: "{{.G_BUILD_DIR}}/docs"
+  G_DOCS_HTML_DIR: "{{.G_DOCS_BUILD_DIR}}/html"
+  G_DOCS_VENV_DIR: "{{.G_DOCS_BUILD_DIR}}/docs-venv"
+  G_NODE_DEPS_DIR: "{{.G_DOCS_BUILD_DIR}}/docs-node"
+
+  # Doxygen paths
+  G_DOXYFILE_PATH: "{{.ROOT_DIR}}/docs/doxygen/Doxyfile"
+  G_DOXYGEN_CMD: "{{.G_DOCS_VENV_DIR}}/bin/doxygen"
+
+tasks:
+  clean:
+    cmds:
+      - "rm -rf '{{.G_DOCS_BUILD_DIR}}'"
+
+  serve:
+    deps:
+      - "http-server"
+      - "site"
+    cmds:
+      - "npm --prefix '{{.G_NODE_DEPS_DIR}}' exec -- http-server '{{.G_DOCS_HTML_DIR}}' -c-1"
+
+  site:
+    vars:
+      CHECKSUM_FILE: "{{.G_BUILD_DIR}}/{{.TASK | replace \":\" \"#\"}}.md5"
+      OUTPUT_DIR: "{{.G_DOCS_HTML_DIR}}"
+    sources:
+      - "{{.G_DOXYFILE_PATH}}"
+      - "{{.ROOT_DIR}}/docs/**/*"
+      - "{{.ROOT_DIR}}/src/**/*"
+      - "{{.ROOT_DIR}}/taskfile.yaml"
+      - "{{.ROOT_DIR}}/tests/**/*"
+      - "{{.TASKFILE}}"
+    generates: ["{{.CHECKSUM_FILE}}"]
+    deps:
+      - "venv"
+      - task: "utils:checksum:validate"
+        vars:
+          CHECKSUM_FILE: "{{.CHECKSUM_FILE}}"
+          INCLUDE_PATTERNS: ["{{.OUTPUT_DIR}}"]
+    cmds:
+      - |-
+        rm -rf "{{.G_DOCS_HTML_DIR}}"
+        cd "{{.ROOT_DIR}}"
+        {{.G_DOXYGEN_CMD}} "{{.G_DOXYFILE_PATH}}"
+      # This command must be last
+      - task: "utils:checksum:compute"
+        vars:
+          CHECKSUM_FILE: "{{.CHECKSUM_FILE}}"
+          INCLUDE_PATTERNS: ["{{.OUTPUT_DIR}}"]
+
+  http-server:
+    internal: true
+    vars:
+      CHECKSUM_FILE: "{{.G_BUILD_DIR}}/{{.TASK | replace \":\" \"#\"}}.md5"
+      OUTPUT_DIR: "{{.G_NODE_DEPS_DIR}}"
+    sources:
+      - "{{.ROOT_DIR}}/taskfile.yaml"
+      - "{{.TASKFILE}}"
+    generates: ["{{.CHECKSUM_FILE}}"]
+    deps:
+      - ":init"
+      - task: "utils:checksum:validate"
+        vars:
+          CHECKSUM_FILE: "{{.CHECKSUM_FILE}}"
+          INCLUDE_PATTERNS: ["{{.OUTPUT_DIR}}"]
+    cmds:
+      - "rm -rf '{{.OUTPUT_DIR}}'"
+      - "npm --prefix '{{.OUTPUT_DIR}}' install http-server"
+      # This command must be last
+      - task: "utils:checksum:compute"
+        vars:
+          CHECKSUM_FILE: "{{.CHECKSUM_FILE}}"
+          INCLUDE_PATTERNS: ["{{.OUTPUT_DIR}}"]
+
+  venv:
+    internal: true
+    run: "once"
+    deps:
+      - ":init"
+    cmds:
+      - "mkdir -p '{{.G_DOCS_VENV_DIR}}'"
+      - task: "utils:remote:download-and-extract-tar"
+        vars:
+          FILE_SHA256: "e5d6ae24d0bf3f0cdc4d8f146726b89ca323922f19441af99b1872d503665ad6"
+          INCLUDE_PATTERNS:
+            - "bin"
+          OUTPUT_DIR: "{{.G_DOCS_VENV_DIR}}"
+          TAR_FILE: "{{.G_DOCS_BUILD_DIR}}/doxygen-1.14.0.linux.bin.tar.gz"
+          URL: "https://www.doxygen.nl/files/doxygen-1.14.0.linux.bin.tar.gz"