📖 Generate section overviews

Makefile

@@ -238,7 +238,7 @@ $(TOOLS_DIR)/verify_boilerplate.py:
 
 .PHONY: verify-boilerplate
 verify-boilerplate: $(TOOLS_DIR)/verify_boilerplate.py
-	$(TOOLS_DIR)/verify_boilerplate.py --boilerplate-dir=hack/boilerplate --skip docs
+	$(TOOLS_DIR)/verify_boilerplate.py --boilerplate-dir=hack/boilerplate --skip docs/venv
 
 ifdef ARTIFACT_DIR
 GOTESTSUM_ARGS += --junitfile=$(ARTIFACT_DIR)/junit.xml

docs/Dockerfile

@@ -1,3 +1,19 @@
+# syntax=docker/dockerfile:1.4
+
+# Copyright 2023 The KCP Authors.
+#
+# 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.
+
 FROM squidfunk/mkdocs-material
 COPY requirements.txt .
 RUN pip install -r requirements.txt

docs/config/en/mkdocs.yml

@@ -41,7 +41,11 @@ plugins:
   # Docs site search
   - search
   # Use Jinja macros in .md files
-  - macros
+  - macros:
+      # This is relative to the repo root
+      include_dir: 'docs/overrides'
+      # This is relative to docs_dir
+      module_name: '../../main'
   # https://github.com/ncdc/mkdocs-modify-base-url
   # ncdc's small plugin to fix the base_url so the version selector works
   - modify-base-url:

docs/content/en/developers/index.md

@@ -0,0 +1,3 @@
+# Information for developers
+
+{% include "partials/section-overview.html" %}

docs/content/en/developers/releasing.md → docs/content/en/developers/publishing-a-new-kcp-release.md

@@ -1,7 +1,6 @@
 ---
-linkTitle: "Publishing"
 description: >
-  kcp release process.
+  Information on the kcp release process
 ---
 
 # Publishing a new kcp release

docs/content/en/developers/replicate-new-resource.md

@@ -1,10 +1,9 @@
 ---
-linkTitle: "Replicating a new resource"
 description: >
-  How to add a new resource for replication.
+  How to add a new resource for replication by the cache server
 ---
 
-# Adding a new resource to the cache server and replication controller
+# Replicating new resources in the cache server
 
 As of today adding a new resource for replication is a manual process that consists of the following steps:
 

docs/content/en/investigations/index.md

@@ -0,0 +1,3 @@
+# Investigations
+
+{% include "partials/section-overview.html" %}

docs/overrides/partials/section-overview.html

@@ -0,0 +1,4 @@
+{% for item in section_items(page, navigation, config) %}
+## [{{ item.title }}]({{ item.url }})
+{{ item.meta.description or '' }}
+{% endfor %}

docs/requirements.txt

@@ -8,5 +8,6 @@ mkdocs-macros-plugin==0.7.0
 mkdocs-material==9.0.11
 mkdocs-material-extensions==1.1.1
 mkdocs-modify-base-url==0.0.2
+mkdocs-simple-hooks==0.1.5
 Pygments==2.14.0
 pymdown-extensions==9.9.2