Merge pull request #2808 from ncdc/doc-the-docs

🌱 docs: document the process

docs/README.md

@@ -0,0 +1,48 @@
+# kcp Documentation Setup
+
+## Overview
+
+Our documentation is powered by [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) with some 
+additional plugins and tools:
+
+- [awesome-pages plugin](https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin)
+- [macros plugin](https://mkdocs-macros-plugin.readthedocs.io/en/latest/)
+- [mike](https://github.com/jimporter/mike) for multiple version support
+
+We have support in place for multiple languages (i18n), although we currently only have documentation in English. If 
+you're interested in contributing translations, please let us know!
+
+## File structure
+
+All documentation-related items live in `docs` (with the small exception of various `make` targets and some helper 
+scripts in `hack`).
+
+The structure of `docs` is as follows:
+
+| Path                        | Description                                                                       |
+|-----------------------------|-----------------------------------------------------------------------------------|
+| config/$language/mkdocs.yml | Language-specific `mkdocs` configuration.                                         |
+| content/$language           | Language-specific website content.                                                |
+| generated/branch            | All generated content for all languages for the current version.                  |
+| generated/branch/$language  | Generated content for a single language. Never added to git.                      |
+| generated/branch/index.html | Minimal index for the current version that redirects to the default language (en) |
+| overrides                   | Global (not language-specific) content.                                           |
+| Dockerfile                  | Builds the kcp-docs image containing mkdocs + associated tooling.                 |
+| mkdocs.yml                  | Minimal `mkdocs` configuration for `mike` for multi-version support.              |
+| requirements.txt            | List of Python modules used to build the site.                                    |
+
+## Publishing Workflow
+
+All documentation building and publishing is done using GitHub Actions in
+[docs-gen-and-push.yaml](../.github/workflows/docs-gen-and-push.yaml). The overall sequence is:
+
+1. Generate CLI docs
+2. Generate API docs
+3. Run `mkdocs build` for all languages
+4. Run `mike deploy --push`
+
+## Theme Overrides
+
+The goal is to have no full overrides of any theme partials. We currently override `header.html` to customize the 
+way the language selection dropdown is rendered. We are working with the theme developers to see if we can help make 
+some changes upstream that don't require an override.

docs/config/en/mkdocs.yml

@@ -2,47 +2,70 @@ site_name: kcp Documentation
 repo_url: https://github.com/kcp-dev/kcp
 site_url: https://docs.kcp.io/kcp/
 
+# Site content
 docs_dir: '../../content/en'
+# Where to generate
 site_dir: '../../generated/branch/en'
 
 theme:
   name: material
   language: en
+  # Common files such as images, stylesheets, theme overrides
   custom_dir: '../../overrides/'
   features:
+    # Enable navigation section index pages, so we don't see Concepts > Concepts
     - navigation.indexes
+    # Enable a copy button in code blocks
     - content.code.copy
+    # Enable annotations on specific lines in code blocks
     - content.code.annotate
   logo: logo.png
   favicon: favicons/favicon.ico
 
 extra:
+  # This is needed so certain links, such as the language switcher, include the correct version.
   git_version: !ENV [GITHUB_REF_NAME, 'main']
   version:
+    # Enable mike for multi-version selection
     provider: mike
+  # Configure supported languages
   alternate:
     - name: English
       link: en
       lang: en
 
 plugins:
+  # https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin
+  # Greater control over how navigation links are shown
   - awesome-pages
+  # Docs site search
   - search
+  # Use Jinja macros in .md files
   - macros
+  # 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:
       prefix: '../'
 
 markdown_extensions:
+  # Code block highlighting
   - pymdownx.highlight:
+      # Allows linking directly to specific lines in code blocks
       anchor_linenums: true
+  # Inline code block highlighting
   - pymdownx.inlinehilite
+  # Lets you embed content from another file
   - pymdownx.snippets
+  # Arbitrary nesting of code/content blocks inside each other
   - pymdownx.superfences
+  # Enable note/warning/etc. callouts
   - admonition
 
+# Our CSS
 extra_css:
   - stylesheets/kcp.css
 
+# Live reload if any of these change when running 'mkdocs serve'
 watch:
   - mkdocs.yml
   - ../../content/en

docs/mkdocs.yml

@@ -1,3 +1,8 @@
+# Config file for mike
+
 site_name: kcp Documentation
 site_url: https://docs.kcp.io/kcp/
+
+# Always point at the output directory for the current checkout/branch.
+# 'mike deploy <version>' controls which version this is ultimately served as.
 docs_dir: generated/branch