ENG-10642: Improve config docs with env var columns and responsive tables by masenf · Pull Request #6819 · reflex-dev/reflex

masenf · 2026-07-28T23:51:23Z

Type of change

New feature (non-breaking change which adds functionality)
This change requires a documentation update

Summary

This PR improves the documentation for Reflex configuration and environment variables by:

Responsive table layouts for API reference pages: Tables now stack descriptions into a separate row on narrow containers, eliminating horizontal scrolling while keeping descriptions readable. Uses Tailwind container queries to adapt at breakpoints like @2xl and @4xl.
Environment variable columns in config docs: The rx.Config API reference now includes an "Environment Variable" column showing the REFLEX_* prefix for each field, making it clear how to override config via environment variables.
Enhanced configuration documentation: Updated docs/advanced_onboarding/configuration.md with:
- Clarified environment variable override behavior with REFLEX_ prefix
- New sections on .env file loading, app module configuration, ports/hosts/URLs, CORS, path prefixes, and plugins
- Links to the config reference for environment variable names
Improved docstring inheritance: Fixed reflex-docgen to merge Attributes sections from base classes in MRO order, so inherited fields (like those in rx.Config inheriting from BaseConfig) get their descriptions from the base class docstring. This eliminates duplicate field listings and ensures all fields are documented.
Markdown rendering flexibility: Added dedent parameter to render_markdown() to allow callers to opt out of whitespace normalization when markdown is already formatted.

Changes

Core changes:

docs/app/reflex_docs/pages/docs/source.py: Added stacked_description_rows() and stacked_description_header() helpers to build responsive tables with container-query-based stacking. Updated format_fields() to support an optional env_var_prefix parameter that adds an environment variable column.
packages/reflex-docgen/src/reflex_docgen/_class.py: Added _attributes_from_mro() to merge docstring Attributes sections from base classes, fixing inherited field descriptions.
docs/app/reflex_docs/pages/docs/env_vars.py: Refactored environment variable table to use the new responsive table helpers.
docs/app/agent_files/_plugin.py: Updated markdown generation to include environment variable columns when env_var_prefix is provided.
packages/reflex-site-shared/src/reflex_site_shared/docs/markdown.py: Added dedent parameter to render_markdown().
docs/app/reflex_docs/pages/docs/apiref.py: Simplified module list and added env_var_prefixes dict to enable env var columns for rx.Config.
docs/advanced_onboarding/configuration.md: Expanded with detailed sections on environment variables, .env files, app module configuration, ports/hosts, CORS, path prefixes, and plugins.

Tests:

tests/units/docgen/test_class_and_component.py: Added test_inherited_fields_get_base_docstring_descriptions() and test_config_fields_documented_once_with_descriptions() to verify inherited field descriptions and that all rx.Config fields are documented.
tests/units/reflex_site_shared/docs/test_markdown.py: Added test_render_markdown_dedent_kwarg_controls_whitespace_normalization() to verify the new dedent parameter.

Test Plan

Unit tests added for inherited field documentation and config field completeness
Unit tests added for markdown rendering with dedent parameter
Existing tests pass with the refactored responsive table helpers
Documentation site renders correctly with environment variable columns in config reference and responsive stacking on narrow viewports

https://claude.ai/code/session_012ZK7KxuaTb2HePTSBFFpJp

- reflex-docgen: merge docstring Attributes sections across the MRO so inherited fields keep their base-class descriptions; drop the extra_fields workaround that listed every Config field twice on the api-reference Config page. - Add an Environment Variable column to the generated Config fields table so every REFLEX_* override (e.g. REFLEX_ENV_FILE) is listed and searchable; cross-link it from the Environment Variables page. - Remove the low-value "Key Configuration Areas" section from the Config docstring. - Rewrite the advanced-onboarding configuration page: correct the env var example (REFLEX_FRONTEND_PORT, not FRONTEND_PORT) and document env_file/python-dotenv, the app module, ports/hosts/URLs, CORS, deploy_url, path prefixes, and plugins (config and env string forms). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012ZK7KxuaTb2HePTSBFFpJp

…ontend The frontend substitutes its own domain when api_url points at localhost, so a backend reachable at the same address as the frontend works without setting api_url; clarify this on the onboarding page and in the Config docstring. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012ZK7KxuaTb2HePTSBFFpJp

avoid accidentally rendering inline triple-quoted strings as code block when passing them to `render_markdown`

the `internal` flag is not preserved through the `env_var` -> `EnvVar` translation, so we can't key off of it. Instead, all internal env vars get "__" prepended to the name, so just use that to make the determination.

The Config fields table (with its env var column) and the Environment Variables table were too wide for normal displays, forcing horizontal scrolling just to read descriptions. Using Tailwind container queries, the description column now stays in-row only when the container is wide enough; below that each entry renders as two lines, with the description spanning the full table width on the second line. The radix row divider is suppressed between the two lines of one logical row so entries stay visually grouped. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012ZK7KxuaTb2HePTSBFFpJp

chatgpt-codex-connector · 2026-07-28T23:51:28Z

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

greptile-apps · 2026-07-28T23:53:44Z

Greptile Summary

The PR expands configuration documentation and improves generated API-reference tables.

Documents config environment variables, dotenv loading, network settings, path prefixes, CORS, and plugins.
Adds responsive description rows and environment-variable columns to API-reference tables.
Inherits attribute descriptions through class MROs and adds configurable Markdown dedenting.
Adds regression tests for inherited field documentation and Markdown whitespace handling.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
docs/advanced_onboarding/configuration.md	Expands the configuration guide; the previously questioned dotenv precedence statements match the current implementation.
docs/app/reflex_docs/pages/docs/source.py	Adds responsive table helpers and optional environment-variable columns for generated field documentation.
packages/reflex-docgen/src/reflex_docgen/_class.py	Merges inherited Attributes documentation in MRO order so subclass descriptions take precedence.
packages/reflex-site-shared/src/reflex_site_shared/docs/markdown.py	Makes common-indent normalization the default while allowing callers to disable it.
tests/units/docgen/test_class_and_component.py	Covers inherited descriptions, subclass overrides, uniqueness, and completeness of Config fields.
tests/units/reflex_site_shared/docs/test_markdown.py	Verifies that the dedent option controls recognition of indented executable Markdown blocks.

_{Reviews (2): Last reviewed commit: "docs: stack table descriptions below fie..." | Re-trigger Greptile}

codspeed-hq · 2026-07-28T23:54:03Z

Merging this PR will not alter performance

✅ 26 untouched benchmarks
⏩ 8 skipped benchmarks¹

_{Comparing claude/reflex-config-docs-47iycz (22273e4) with main (b9d112d)}

8 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

linear-code · 2026-07-31T16:49:54Z

ENG-10642

claude and others added 5 commits July 27, 2026 18:29

render_markdown helper automatically uses textwrap.dedent

f5c971d

avoid accidentally rendering inline triple-quoted strings as code block when passing them to `render_markdown`

filter internal env vars by name starting with "__"

87b2ee7

the `internal` flag is not preserved through the `env_var` -> `EnvVar` translation, so we can't key off of it. Instead, all internal env vars get "__" prepended to the name, so just use that to make the determination.

masenf requested review from a team and Alek99 as code owners July 28, 2026 23:51

greptile-apps Bot reviewed Jul 28, 2026

View reviewed changes

Comment thread docs/advanced_onboarding/configuration.md

masenf added the skip-changelog For doc/internal changes label Jul 31, 2026

masenf changed the title ~~Improve config docs with env var columns and responsive tables~~ ENG-10642: Improve config docs with env var columns and responsive tables Jul 31, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

ENG-10642: Improve config docs with env var columns and responsive tables - #6819

ENG-10642: Improve config docs with env var columns and responsive tables#6819
masenf wants to merge 5 commits into
mainfrom
claude/reflex-config-docs-47iycz

masenf commented Jul 28, 2026

Uh oh!

chatgpt-codex-connector Bot commented Jul 28, 2026

Uh oh!

Uh oh!

greptile-apps Bot commented Jul 28, 2026 •

edited

Loading

Important Files Changed

Uh oh!

codspeed-hq Bot commented Jul 28, 2026

Uh oh!

linear-code Bot commented Jul 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

masenf commented Jul 28, 2026

Type of change

Summary

Changes

Core changes:

Tests:

Test Plan

Uh oh!

chatgpt-codex-connector Bot commented Jul 28, 2026

Uh oh!

Uh oh!

greptile-apps Bot commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Uh oh!

codspeed-hq Bot commented Jul 28, 2026

Merging this PR will not alter performance

Footnotes

Uh oh!

linear-code Bot commented Jul 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

greptile-apps Bot commented Jul 28, 2026 •

edited

Loading