ci(i): Add check to keep table of contents up-to-date

.github/workflows/check-documentation.yml

@@ -0,0 +1,102 @@
+# Copyright 2024 Democratized Data Foundation
+#
+# Use of this software is governed by the Business Source License
+# included in the file licenses/BSL.txt.
+#
+# As of the Change Date specified in that file, in accordance with
+# the Business Source License, use of this software will be governed
+# by the Apache License, Version 2.0, included in the file
+# licenses/APL.txt.
+
+# This workflow checks that all documentation is up to date.
+# If any documentation is not up to date then this action will fail.
+name: Check Documentation Workflow
+
+on:
+  pull_request:
+    branches:
+      - master
+      - develop
+
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+    branches:
+      - master
+      - develop
+
+jobs:
+  check-cli-documentation:
+    name: Check cli documentation job
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code into the directory
+        uses: actions/checkout@v3
+
+      - name: Setup Go environment explicitly
+        uses: actions/setup-go@v3
+        with:
+          go-version: "1.21"
+          check-latest: true
+
+      - name: Try generating cli documentation
+        run: make docs:cli
+
+      - name: Check no new changes exist
+        uses: tj-actions/verify-changed-files@v20
+        with:
+          fail-if-changed: true
+          files: |
+             docs/website/references/cli
+
+  check-http-documentation:
+    name: Check http documentation job
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code into the directory
+        uses: actions/checkout@v3
+
+      - name: Setup Go environment explicitly
+        uses: actions/setup-go@v3
+        with:
+          go-version: "1.21"
+          check-latest: true
+
+      - name: Try generating http documentation
+        run: make docs:http
+
+      - name: Check no new changes exist
+        uses: tj-actions/verify-changed-files@v20
+        with:
+          fail-if-changed: true
+          files: |
+             docs/website/references/http
+
+  check-readme-toc:
+    name: Check readme toc job
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code into the directory
+        uses: actions/checkout@v3
+
+      - name: Setup Go environment explicitly
+        uses: actions/setup-go@v3
+        with:
+          go-version: "1.21"
+          check-latest: true
+
+      - name: Try generating readme toc
+        run: make toc
+
+      - name: Check no new changes exist
+        uses: tj-actions/verify-changed-files@v20
+        with:
+          fail-if-changed: true
+          files: |
+             README.md

Makefile

@@ -357,6 +357,7 @@ docs:
 	@$(MAKE) docs\:cli
 	@$(MAKE) docs\:manpages
 	@$(MAKE) docs\:http
+	@$(MAKE) toc
 
 .PHONY: docs\:cli
 docs\:cli:
@@ -375,3 +376,7 @@ docs\:manpages:
 docs\:godoc:
 	godoc -http=:6060
 	# open http://localhost:6060/pkg/github.com/sourcenetwork/defradb/
+
+.PHONY: toc
+toc:
+	bash tools/scripts/md-toc/gh-md-toc --insert --no-backup --hide-footer --skip-header README.md

README.md

@@ -15,29 +15,29 @@ DefraDB is a user-centric database that prioritizes data ownership, personal pri
 
 Read the documentation on [docs.source.network](https://docs.source.network/).
 
+
 ## Table of Contents
 
-- [Install](#install)
-- [Key Management](#key-management)
-- [Start](#start)
-- [Configuration](#configuration)
-- [External port binding](#external-port-binding)
-- [Add a schema type](#add-a-schema-type)
-- [Create a document instance](#create-a-document-instance)
-- [Query documents](#query-documents)
-- [Obtain document commits](#obtain-document-commits)
-- [DefraDB Query Language (DQL)](#defradb-query-language-dql)
-- [Peer-to-peer data synchronization](#peer-to-peer-data-synchronization)
-  - [Pubsub example](#pubsub-example)
-  - [Collection subscription example](#collection-subscription-example)
-  - [Replicator example](#replicator-example)
-- [Securing the HTTP API with TLS](#securing-the-http-api-with-tls)
-- [Access Control System](#access-control-system)
-- [Supporting CORS](#supporting-cors)
-- [Backing up and restoring](#backing-up-and-restoring)
-- [Community](#community)
-- [Licensing](#licensing)
-- [Contributors](#contributors)
+<!--ts-->
+   * [Install](#install)
+   * [Key Management](#key-management)
+   * [Start](#start)
+   * [Configuration](#configuration)
+   * [External port binding](#external-port-binding)
+   * [Add a schema type](#add-a-schema-type)
+   * [Create a document](#create-a-document)
+   * [Query documents](#query-documents)
+   * [Obtain document commits](#obtain-document-commits)
+   * [DefraDB Query Language (DQL)](#defradb-query-language-dql)
+   * [Peer-to-peer data synchronization](#peer-to-peer-data-synchronization)
+   * [Securing the HTTP API with TLS](#securing-the-http-api-with-tls)
+   * [Access Control System](#access-control-system)
+   * [Supporting CORS](#supporting-cors)
+   * [Backing up and restoring](#backing-up-and-restoring)
+   * [Community](#community)
+   * [Licensing](#licensing)
+   * [Contributors](#contributors)
+<!--te-->
 
 DISCLAIMER: At this early stage, DefraDB does not offer data encryption, and the default configuration exposes the database to the network. The software is provided "as is" and is not guaranteed to be stable, secure, or error-free. We encourage you to experiment with DefraDB and provide feedback, but please do not use it for production purposes until it has been thoroughly tested and developed.