add documentation publishing through github-pages by nixpanic · Pull Request #6380 · ceph/ceph-csi

nixpanic · 2026-07-03T14:33:00Z

The result of the PR is available for review at https://ceph.github.io/ceph-csi/

New documentation like docs/index.md has been written by IBM Bob. Scripts and
configuration to render the site was initially created by Bob as well, but
needed some modifications and cleanups.

The design and tooling is based on what Rook uses for https://rook.io/docs/

Madhu-1 · 2026-07-06T08:17:07Z

+  push:
+    branches:
+      - devel
+      - staging/docs  # TODO: remove me


Yes, it's there for generating the published docs when pushing to that branch as a maintainer of the repository. I'll drop it when there are no other comments to address anymore.

@Madhu-1 , this is removed now.

Rakshith-R · 2026-07-09T07:43:34Z

+          path: ~/.cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material


Can we tag it by hash to make it more secure ? 😅

Sure, added the version to build.env.

Also did a test run with the specified version.

Copilot

Pull request overview

Adds a MkDocs (Material theme) documentation site for Ceph-CSI and publishes it to GitHub Pages, integrating docs-site generation into the repo’s build/developer tooling.

Changes:

Add MkDocs configuration (mkdocs.yml) and a new documentation landing page (docs/index.md).
Add a GitHub Actions workflow to publish docs to GitHub Pages on pushes to devel.
Introduce a make mkdocs target and add MkDocs tooling/version wiring via build.env and the development container image.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
scripts/Dockerfile.devel	Installs Python/pip and MkDocs Material in the dev image (currently unpinned).
mkdocs.yml	New MkDocs site configuration and navigation for the `docs/` tree.
Makefile	Adds `mkdocs` build target; expands `clean` to remove `_output/`.
docs/index.md	New docs homepage content and links.
build.env	Adds pinned `MKDOCS_MATERIAL` version variable.
.github/workflows/publish-docs.yaml	New workflow to install MkDocs Material and deploy to GitHub Pages via `mkdocs gh-deploy`.

+site_name: Ceph-CSI Documentation
+site_description: Container Storage Interface (CSI) drivers for Ceph storage
+site_author: Ceph-CSI Contributors
+site_url: https://ceph.github.com/ceph-csi


Pull request has been modified.

nixpanic · 2026-07-09T12:43:01Z

@Rakshith-R , addressed Copilots comments too now.

Copilot

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 2 comments.

Add mkdocs-material to the development container and create infrastructure for building documentation: - Install python3-pip and mkdocs-material in Dockerfile.devel - Create mkdocs.yml with Material theme and navigation structure - Add 'make containerized-build TARGET=mkdocs' support to build documentation in container with output to _output/docs The documentation can now be built with: make containerized-build TARGET=mkdocs Assisted-by: AskBob <[email protected]> Signed-off-by: Niels de Vos <[email protected]>

Create a comprehensive landing page (docs/index.md) that provides: - Overview of Ceph-CSI and supported storage types - Quick links to key documentation sections - Architecture overview - Contributing and support information Assisted-by: AskBob <[email protected]> Signed-off-by: Niels de Vos <[email protected]>

Signed-off-by: Niels de Vos <[email protected]>

nixpanic · 2026-07-10T07:19:42Z

@Rakshith-R , addressed Copilots comments too now.

And again!

Rakshith-R

Thanks

black-dragon74 · 2026-07-10T07:38:06Z

@nixpanic, LGTM. Can we add dark mode while we are at it?

theme:
  name: material
  favicon: images/favicon.ico
  palette:
    - scheme: slate
      media: "(prefers-color-scheme: dark)"
      toggle:
        icon: material/toggle-switch
        name: Bring back the sunshine
    - scheme: default
      media: "(prefers-color-scheme: light)"
      toggle:
        icon: material/toggle-switch-off-outline
        name: Turn off the lights

nixpanic · 2026-07-10T07:58:12Z

@nixpanic, LGTM. Can we add dark mode while we are at it?

Tried this locally, but the toggle between dark/light does not work. We can look into adding a dark theme later.

mergify · 2026-07-10T07:59:57Z

Deprecation notice: This pull request comes from a fork and was queued with update_method=rebase and update_bot_account impersonation. This capability will be removed on July 1, 2026. After this date, the merge queue will no longer be able to rebase fork pull requests with this configuration. To avoid disruption, switch to update_method=merge in your queue rule.

mergify · 2026-07-10T07:59:59Z

Merge Queue Status

✅ Entered queue — 2026-07-10 07:59 UTC · Rule: default · triggered by merge protections
✅ Checks skipped · PR is already up-to-date
✅ Merged — 2026-07-10 08:00 UTC · at d878fe8ca364e6fea07a8e731d49f1643de9ec4d · rebase

This pull request spent 9 seconds in the queue, including 1 second running CI.

Required conditions to merge

github-review-approved [🛡 GitHub branch protection]
- add documentation publishing through github-pages #6380

nixpanic added ci/skip/e2e skip running e2e CI jobs ci/skip/multi-arch-build skip building on multiple architectures component/docs Issues and PRs related to documentation labels Jul 3, 2026

nixpanic force-pushed the docs/mkdocs branch from 9f96b6e to b12043a Compare July 3, 2026 14:44

nixpanic requested a review from a team July 6, 2026 08:16

Madhu-1 reviewed Jul 6, 2026

View reviewed changes

nixpanic requested review from a team and Madhu-1 July 6, 2026 08:38

Rakshith-R reviewed Jul 9, 2026

View reviewed changes

nixpanic force-pushed the docs/mkdocs branch from b12043a to 97d367c Compare July 9, 2026 08:36

nixpanic requested a review from Rakshith-R July 9, 2026 08:38

Rakshith-R requested a review from Copilot July 9, 2026 08:38

Copilot started reviewing on behalf of Rakshith-R July 9, 2026 08:39 View session

Madhu-1 previously approved these changes Jul 9, 2026

View reviewed changes

Copilot AI reviewed Jul 9, 2026

View reviewed changes

nixpanic force-pushed the docs/mkdocs branch from 97d367c to a70bfb5 Compare July 9, 2026 12:41

nixpanic requested a review from Madhu-1 July 9, 2026 12:42

Rakshith-R requested a review from Copilot July 10, 2026 06:21

Copilot started reviewing on behalf of Rakshith-R July 10, 2026 06:21 View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

Comment thread Makefile Outdated

Comment thread scripts/Dockerfile.devel

nixpanic added 5 commits July 10, 2026 09:19

ci: add documentation publishing through github-pages

c4d8953

Signed-off-by: Niels de Vos <[email protected]>

build: generate docs with selected mkdocs-material version

480e861

Signed-off-by: Niels de Vos <[email protected]>

doc: move Ceph logo to subdirectory of docs/

d878fe8

Signed-off-by: Niels de Vos <[email protected]>

nixpanic force-pushed the docs/mkdocs branch from 126b144 to d878fe8 Compare July 10, 2026 07:19

Rakshith-R approved these changes Jul 10, 2026

View reviewed changes

Rakshith-R requested a review from a team July 10, 2026 07:31

black-dragon74 approved these changes Jul 10, 2026

View reviewed changes

mergify Bot merged commit 7e9580b into ceph:devel Jul 10, 2026
16 checks passed

Conversation

nixpanic commented Jul 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Madhu-1 Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

nixpanic Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

nixpanic Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

Rakshith-R Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

nixpanic Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nixpanic commented Jul 9, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

nixpanic commented Jul 10, 2026

Uh oh!

Rakshith-R left a comment

Choose a reason for hiding this comment

Uh oh!

black-dragon74 commented Jul 10, 2026

Uh oh!

nixpanic commented Jul 10, 2026

Uh oh!

mergify Bot commented Jul 10, 2026

Uh oh!

mergify Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge Queue Status

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

nixpanic commented Jul 3, 2026 •

edited

Loading

mergify Bot commented Jul 10, 2026 •

edited

Loading