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:38Z

+)
+```
+
+Multiple files can be passed separated by `os.pathsep` (`:` on Linux/macOS, `;` on Windows); when several files set the same variable, the first file in the list takes precedence. Values from an env file override variables already present in the environment.


Correct dotenv precedence description

The documentation reverses the precedence between dotenv values and variables already present in the process environment. Explicit process-environment values take precedence, so this statement gives users the wrong expectation when both sources define the same variable.

Suggested change

Multiple files can be passed separated by `os.pathsep` (`:` on Linux/macOS, `;` on Windows); when several files set the same variable, the first file in the list takes precedence. Values from an env file override variables already present in the environment.

Multiple files can be passed separated by `os.pathsep` (`:` on Linux/macOS, `;` on Windows); when several files set the same variable, the first file in the list takes precedence. Variables already present in the environment override values from an env file.

Knowledge Base Used: Config and Environment System

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

Greptile Summary

Improves configuration documentation and API-reference tables.

Adds responsive description rows and environment-variable columns to generated references.
Inherits field descriptions from base-class docstrings.
Adds optional Markdown whitespace dedenting and corresponding tests.
Expands guidance for dotenv files, deployment URLs, CORS, path prefixes, and plugins.

Confidence Score: 4/5

The PR appears safe to merge after correcting the non-blocking dotenv precedence documentation.

The implementation changes have no identified blocking defect, but the configuration guide currently tells users that dotenv values override existing process variables even though explicit environment values retain precedence.

Files Needing Attention: docs/advanced_onboarding/configuration.md

Important Files Changed

Filename	Overview
docs/advanced_onboarding/configuration.md	Substantially expands configuration guidance, but reverses dotenv-versus-process-environment precedence in one sentence.
docs/app/reflex_docs/pages/docs/source.py	Adds reusable responsive table helpers and Config environment-variable columns without an identified functional defect.
docs/app/reflex_docs/pages/docs/env_vars.py	Migrates the environment-variable reference to responsive rows and correctly excludes internal variables by their generated name prefix.
packages/reflex-docgen/src/reflex_docgen/_class.py	Merges inherited Attributes documentation in MRO order so subclass fields retain the nearest applicable descriptions.
packages/reflex-site-shared/src/reflex_site_shared/docs/markdown.py	Dedents Markdown by default while providing an explicit opt-out for whitespace-sensitive callers.
docs/app/agent_files/_plugin.py	Aligns generated Markdown references with inherited Config fields and the new environment-variable column.

_{Reviews (1): 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. ↩

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

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!

greptile-apps Bot Jul 28, 2026

Uh oh!

greptile-apps Bot commented Jul 28, 2026

Important Files Changed

Uh oh!

codspeed-hq Bot commented Jul 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	Multiple files can be passed separated by `os.pathsep` (`:` on Linux/macOS, `;` on Windows); when several files set the same variable, the first file in the list takes precedence. Values from an env file override variables already present in the environment.
	Multiple files can be passed separated by `os.pathsep` (`:` on Linux/macOS, `;` on Windows); when several files set the same variable, the first file in the list takes precedence. Variables already present in the environment override values from an env file.

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!

greptile-apps Bot Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot commented Jul 28, 2026

Greptile Summary

Confidence Score: 4/5

Important Files Changed

Uh oh!

codspeed-hq Bot commented Jul 28, 2026

Merging this PR will not alter performance

Footnotes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants