Skip to content

Conversation

@RobMulla
Copy link
Contributor

@RobMulla RobMulla commented Dec 16, 2025

Description

Improving the documentation landing pages to provide context and helpful summaries instead of bare lists of links.

Changes

  • Run MaxText (docs/run_maxtext.md): Categorized execution methods into "Local & Single Host" (e.g., Localhost, Single NVIDIA GPU) and "Multi-Host & Cluster" (XPK, Pathways). Added descriptions for each method.
  • How-to Guides (docs/guides.md): Grouped guides into "Performance & Optimization", "Data & Storage", and "Development Workflows" with brief summaries.
  • Reference (docs/reference.md): Organized into "Core Concepts" and "Benchmarks & Models" to help users find technical details faster.

Motivation

New users landing on these pages previously saw only a list of file links without context. These changes help users navigate to the right document based on their specific goal (e.g., "I want to run locally" vs "I want to optimize performance").

Verification

  • Built documentation locally (sphinx-build) to verify rendering and links.

Checklist

Before submitting this PR, please make sure (put X in square brackets):

  • I have performed a self-review of my code. For an optional AI review, add the gemini-review label.
  • I have necessary comments in my code, particularly in hard-to-understand areas.
  • I have run end-to-end tests tests and provided workload links above if applicable.
  • I have made or will make corresponding changes to the doc if needed, including adding new documentation pages to the relevant Table of Contents (toctree directive) as explained in our documentation.

Copy link
Collaborator

@jacoguzo jacoguzo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These look good but I think there will be many conflicts with this PR. Maybe these descriptions could be ported into the descriptions of the cards. https://github.com/AI-Hypercomputer/maxtext/pull/2821/files

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.

2 participants