Skip to content

blog process to add authors et all - #1123

Open
negin513 wants to merge 6 commits into
NVIDIA:mainfrom
negin513:docs/mkdocs-material
Open

negin513 wants to merge 6 commits into
NVIDIA:mainfrom
negin513:docs/mkdocs-material

Conversation

@negin513

Copy link
Copy Markdown
Member

Earth2Studio Pull Request

Description

Converts the documentation build from zensical back to mkdocs-material and
cleans up the blog and docs CI:

  • Build: zensical build/serve → mkdocs build/serve in the Makefiles and
    CI action; drop the zensical dependency and the mkdocs_badges.zensical
    markdown extension (the badges mkdocs plugin provides the same rendering).
    This also aligns the local/artifact build with what mike deploy has been
    publishing all along.
  • Blog: let the Material blog plugin generate the index, archive, and
    category pages instead of hand-written listings; add post authors via
    docs/blog/.authors.yml.
  • Navigation: expand sidebar sections by default (navigation.expand).
  • CI: e2s-docs-light now only runs when docs content (including blog
    posts), examples/recipes, the docs toolchain, or the pipeline itself
    changes — other pushes skip the H100 docs rebuild (workflow_dispatch
    still forces one, e.g. after docstring-only changes).
  • Lint: add a codespell pre-commit hook over hand-written docs
    (README, mkdocs.yml, non-generated docs/**/*.md) and wire it into
    make lint.

Verified: make docs end-to-end, uv lock --check, badge autosummary/filter
rendering, blog author rendering, sitemap, and mike compatibility.

Known follow-up: docs/blog/archive.md, docs/blog/categories.md, and
docs/blog/categories/documentation.md are now orphaned duplicates of the
plugin-generated pages and should be deleted.

Checklist

  • I am familiar with the Contributing Guidelines.
  • New or existing tests cover these changes.
  • The documentation is up to date with these changes.
  • The CHANGELOG.md is up to date with these changes.
  • An issue is linked to this pull request.
  • Assess and address Greptile feedback (AI code review bot for guidance; use discretion, addressing all feedback is not required).

Dependencies

Removes zensical; no new dependencies (codespell runs via pre-commit).

🤖 Generated with Claude Code

Swap the zensical build engine for mkdocs: update Makefiles and CI step
names, drop the zensical dependency and its markdown-extension shim
(the badges mkdocs plugin covers rendering), and fold the blog nav into
the Material blog plugin's generated navigation.
- e2s-docs-light now only runs on pushes touching docs content (including
  blog posts), the examples/recipes sources, the docs toolchain, or the
  pipeline itself; other pushes skip the H100 docs rebuild. Use
  workflow_dispatch to force a rebuild after docstring-only changes.
- Add codespell pre-commit hook over hand-written docs (README, mkdocs.yml,
  non-generated docs/*.md) and wire it into 'make lint' for CI.
@copy-pr-bot

copy-pr-bot Bot commented Aug 29, 2026

Copy link
Copy Markdown

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

@greptile-apps

greptile-apps Bot commented Aug 29, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

Converts documentation builds from Zensical back to MkDocs Material and simplifies blog generation, while narrowing automatic light-doc rebuilds and adding documentation spell-checking.

  • Replaces Zensical build and serve commands with MkDocs.
  • Lets the Material blog plugin generate blog listings, archives, and categories.
  • Adds blog author metadata and expanded navigation.
  • Adds path filtering for light-doc deployments and a codespell pre-commit hook.
  • Removes the Zensical dependency and corresponding lock entries.

Confidence Score: 5/5

The PR appears safe to merge, with no concrete blocking or independently actionable non-blocking defects identified.

The MkDocs migration, blog metadata, lint integration, and dependency cleanup are internally aligned, while the intentionally deferred source-only deployments and orphaned blog pages are already documented by the author.

Important Files Changed

Filename Overview
.github/workflows/e2s-docs-light.yml Narrows automated documentation deployments to selected documentation and toolchain paths; omitted source-only documentation updates are explicitly documented.
Makefile Replaces Zensical documentation commands with equivalent MkDocs build and serve commands and adds codespell to linting.
docs/Makefile Updates standalone documentation targets and variables from Zensical to MkDocs.
mkdocs.yml Removes the Zensical badge extension, enables expanded navigation, and delegates blog navigation generation to the Material blog plugin.
.pre-commit-config.yaml Adds codespell for hand-written Markdown documentation while excluding generated documentation trees.
pyproject.toml Removes Zensical from the documentation dependency group.
uv.lock Synchronizes the lock metadata by removing the Zensical documentation dependency.
docs/blog/.authors.yml Defines author metadata referenced by the two updated blog posts.
docs/blog/index.md Removes the hand-written post listing so the configured Material blog plugin can generate it.

Reviews (1): Last reviewed commit: "Scope docs CI to docs changes and add co..." | Re-trigger Greptile

@negin513 negin513 changed the title Better blog process blog process to add authors et all Aug 29, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant