Migrate doc generation tooling

.github/workflows/docs.yml

@@ -47,6 +47,8 @@ jobs:
       run: make lint-yaml
     - name: Lint prose
       run: make lint-prose
+    - name: Lint Python
+      run: make lint-python
     - name: Build
       run: make build
 

.github/workflows/update-config-docs.yml

@@ -0,0 +1,61 @@
+# This file is part of Dependency-Track.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) OWASP Foundation. All Rights Reserved.
+name: Update Config Documentation
+
+on:
+  workflow_dispatch: {}
+
+permissions: {}
+
+jobs:
+  generate-docs:
+    name: Generate Documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+      pull-requests: write
+    if: "${{ github.repository_owner == 'DependencyTrack' }}"
+    steps:
+    - name: Checkout Repository
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      with:
+        persist-credentials: false
+    - name: Checkout API Server Repository
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      with:
+        repository: DependencyTrack/hyades-apiserver
+        path: hyades-apiserver
+        persist-credentials: false
+    - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+      with:
+        enable-cache: false
+    - name: Generate API Server Documentation
+      run: >-
+        make generate-config-docs
+        APISERVER_PROPERTIES=hyades-apiserver/apiserver/src/main/resources/application.properties
+    - name: Create Pull Request
+      uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
+      with:
+        add-paths: "docs/reference/configuration/properties.md"
+        branch: update-config-docs
+        body: "Updates configuration documentation."
+        commit-message: Update config docs
+        delete-branch: true
+        labels: documentation
+        signoff: true
+        title: Update config docs

.github/workflows/update-openapi-docs.yml

@@ -0,0 +1,61 @@
+# This file is part of Dependency-Track.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) OWASP Foundation. All Rights Reserved.
+name: Update OpenAPI Documentation
+
+on:
+  workflow_dispatch: {}
+
+permissions: {}
+
+jobs:
+  update-docs:
+    name: Update Documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+      pull-requests: write
+    if: "${{ github.repository_owner == 'DependencyTrack' }}"
+    steps:
+    - name: Checkout Repository
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      with:
+        persist-credentials: false
+    - name: Download OpenAPI Specs
+      env:
+        GH_TOKEN: "${{ github.token }}"
+      run: |-
+        gh run download --repo DependencyTrack/hyades-apiserver \
+          --name openapi-spec \
+          --dir /tmp/openapi-spec
+    - name: Update Spec Files
+      run: |-
+        cp /tmp/openapi-spec/v1/openapi.yaml \
+          docs/reference/api/openapi-v1.yaml
+        cp /tmp/openapi-spec/v2/openapi.yaml \
+          docs/reference/api/openapi-v2.yaml
+    - name: Create Pull Request
+      uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
+      with:
+        add-paths: "docs/reference/api/openapi-*.yaml"
+        branch: update-openapi-docs
+        body: "Updates OpenAPI documentation."
+        commit-message: Update OpenAPI docs
+        delete-branch: true
+        labels: documentation
+        signoff: true
+        title: Update OpenAPI docs

.github/workflows/update-proto-docs.yml

@@ -0,0 +1,56 @@
+# This file is part of Dependency-Track.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) OWASP Foundation. All Rights Reserved.
+name: Update Protobuf Documentation
+
+on:
+  workflow_dispatch: {}
+
+permissions: {}
+
+jobs:
+  generate-docs:
+    name: Generate Documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+      pull-requests: write
+    if: "${{ github.repository_owner == 'DependencyTrack' }}"
+    steps:
+    - name: Checkout Repository
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      with:
+        persist-credentials: false
+    - name: Checkout API Server Repository
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      with:
+        repository: DependencyTrack/hyades-apiserver
+        path: hyades-apiserver
+        persist-credentials: false
+    - name: Generate Proto Documentation
+      run: make generate-proto-docs APISERVER_DIR=hyades-apiserver
+    - name: Create Pull Request
+      uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
+      with:
+        add-paths: "docs/reference/schemas/*.md"
+        branch: update-proto-docs
+        body: "Updates Protobuf documentation."
+        commit-message: Update proto docs
+        delete-branch: true
+        labels: documentation
+        signoff: true
+        title: Update proto docs

AGENTS.md

@@ -38,6 +38,7 @@ Run the relevant linter after modifying files:
 - **Markdown files** (`docs/**/*.md`, `context/**/*.md`): `make lint-markdown`
 - **Prose quality** (`docs/**/*.md`): `make lint-prose`
 - **YAML files** (`mkdocs.yml`, `.github/**/*.yml`, etc.): `make lint-yaml`
+- **Python files** (`scripts/**/*.py`): `make lint-python`
 - **All at once**: `make lint`
 
 Fix all lint errors before considering work complete.
@@ -49,6 +50,14 @@ Fix all lint errors before considering work complete.
 
 Always verify new or modified pages render correctly with `make build`.
 
+### Generated documentation
+
+Some reference pages are generated from source repositories. Do not edit these files directly.
+
+- **Configuration properties** (`docs/reference/configuration/properties.md`): generated by `scripts/generate_config_docs.py` from `application.properties` in the API server repo. Regenerate with `make generate-config-docs APISERVER_PROPERTIES=<path>`.
+- **Protobuf schemas** (`docs/reference/schemas/{notification,policy}.md`): generated by `protoc-gen-doc` from proto definitions in the API server repo. Regenerate with `make generate-proto-docs APISERVER_DIR=<path>`.
+- **OpenAPI specs** (`docs/reference/api/openapi-*.yaml`): downloaded from API server CI artifacts via the `update-openapi-docs` workflow.
+
 ## Writing conventions
 
 - Do not modify files in `existing-docs/`.

Makefile

@@ -23,7 +23,7 @@ clean:
 	rm -rf site/
 .PHONY: clean
 
-lint: lint-markdown lint-yaml lint-prose
+lint: lint-markdown lint-yaml lint-prose lint-python
 .PHONY: lint
 
 lint-markdown:
@@ -41,6 +41,11 @@ lint-yaml:
 	  yamllint .
 .PHONY: lint-yaml
 
+lint-python:
+	uvx ruff check scripts/
+	uvx ruff format --check scripts/
+.PHONY: lint-python
+
 lint-prose:
 	docker run --rm \
 	  -v "$(shell pwd)":/workdir \
@@ -54,6 +59,24 @@ lint-prose:
 	  docs/
 .PHONY: lint-prose
 
+generate-config-docs:
+	uv run scripts/generate_config_docs.py \
+	  --template scripts/templates/config-docs.md.j2 \
+	  --output docs/reference/configuration/properties.md \
+	  $(APISERVER_PROPERTIES)
+.PHONY: generate-config-docs
+
+generate-proto-docs:
+	docker run -i --rm -u "$$(id -u):$$(id -g)" \
+	  -v "$$(pwd)/docs/reference/schemas:/out" \
+	  -v "$(APISERVER_DIR)/notification/api/src/main/proto/org/dependencytrack/notification/v1:/protos" \
+	  pseudomuto/protoc-gen-doc:1.5 --doc_opt=/out/notification.md.tmpl,notification.md
+	docker run -i --rm -u "$$(id -u):$$(id -g)" \
+	  -v "$$(pwd)/docs/reference/schemas:/out" \
+	  -v "$(APISERVER_DIR)/proto/src/main/proto/org/dependencytrack/policy/v1:/protos" \
+	  pseudomuto/protoc-gen-doc:1.5 --doc_opt=/out/policy.md.tmpl,policy.md
+.PHONY: generate-proto-docs
+
 serve:
 	uv run mkdocs serve --livereload
 .PHONY: serve

README.md

@@ -38,6 +38,17 @@ make lint              # Run all linters
 make lint-markdown     # Markdown (markdownlint)
 make lint-prose        # Prose quality (Vale)
 make lint-yaml         # YAML (yamllint)
+make lint-python       # Python (Ruff)
 ```
 
-Linters run in Docker. Fix all errors before submitting changes.
+Linters run in Docker, except for Python which uses [Ruff](https://docs.astral.sh/ruff/) via `uvx`. Fix all errors before submitting changes.
+
+## Generated documentation
+
+Some reference pages are generated from upstream source repositories and should not be edited directly. GitHub Actions workflows are provided to automate regeneration.
+
+| Content | Source | Workflow | Local command |
+|:--------|:-------|:---------|:--------------|
+| Configuration properties | `application.properties` in [hyades-apiserver](https://github.com/DependencyTrack/hyades-apiserver) | `update-config-docs` | `make generate-config-docs APISERVER_PROPERTIES=<path>` |
+| Protobuf schemas | `.proto` files in [hyades-apiserver](https://github.com/DependencyTrack/hyades-apiserver) | `update-proto-docs` | `make generate-proto-docs APISERVER_DIR=<path>` |
+| OpenAPI specs | CI artifacts from [hyades-apiserver](https://github.com/DependencyTrack/hyades-apiserver) | `update-openapi-docs` | n/a |