Skip to content

Commit d505ef5

Browse files
authored
Simplify XY docs navbar (#374)
* Simplify XY docs navbar * Use GitHub as the navbar CTA * Document published reflex-xy adapter * Remove reflex adapter warning
1 parent d6adb1d commit d505ef5

6 files changed

Lines changed: 67 additions & 81 deletions

File tree

‎docs/app/tests/test_docs_site.py‎

Lines changed: 17 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@
6868
page_with_api_reference_toc,
6969
render_xy_markdown_page,
7070
)
71-
from xy_docs.navbar import XY_GITHUB_STARS, XY_REPOSITORY_URL, xy_docs_navbar
71+
from xy_docs.navbar import XY_REPOSITORY_URL, xy_docs_navbar
7272
from xy_docs.sidebar import (
7373
CHART_FAMILY_SIDEBAR_SECTIONS,
7474
CHART_GALLERY_SIDEBAR_LINK,
@@ -2042,8 +2042,8 @@ def test_xy_sidebar_opens_only_the_current_chart_family(
20422042
)
20432043

20442044

2045-
def test_xy_mobile_navbar_uses_the_official_drawer_button() -> None:
2046-
"""Match the official navbar while retaining its mobile drawer trigger."""
2045+
def test_xy_navbar_uses_xy_links_github_and_the_official_drawer() -> None:
2046+
"""Keep the XY navbar focused while retaining its mobile drawer trigger."""
20472047
component = xy_docs_navbar()
20482048
assert isinstance(component, MemoComponent)
20492049

@@ -2052,22 +2052,28 @@ def test_xy_mobile_navbar_uses_the_official_drawer_button() -> None:
20522052
assert 'href:"/"' in rendered
20532053
assert '"aria-label":"Reflex XY"' in rendered
20542054
assert "M29 16H32V10H39V7H32V4H39V1H29V16" in rendered
2055-
assert 'href:"/docs/"' in rendered
2056-
assert 'href:"/docs/ai/overview/best-practices/"' in rendered
2057-
assert 'href:"/docs/getting-started/introduction/"' in rendered
2058-
assert 'href:"/docs/hosting/deploy-quick-start/"' in rendered
20592055
assert 'href:"/docs/xy/"' in rendered
2060-
assert 'variant:"ghost"},"XY"' in rendered
2056+
assert 'href:"/docs/xy/integrations/reflex/"' in rendered
2057+
assert "Overview" in rendered
2058+
assert "Reflex Integration" in rendered
2059+
assert 'variant:"ghost"},"Build with AI"' not in rendered
2060+
assert 'variant:"ghost"},"Framework"' not in rendered
2061+
assert 'variant:"ghost"},"Cloud"' not in rendered
2062+
assert 'variant:"ghost"},"XY"' not in rendered
2063+
assert "Forum" not in rendered
2064+
assert "Discord Community" not in rendered
2065+
assert 'variant:"primary"' in rendered
2066+
assert "View XY on GitHub -" not in rendered
2067+
assert rendered.count("View XY on GitHub") == 2
2068+
assert 'target:"_blank"' in rendered
2069+
assert 'rel:"noopener noreferrer"' in rendered
20612070
assert "Open sidebar" in rendered
20622071
assert "Menu01Icon" in rendered
20632072
assert "Cancel01Icon" in rendered
20642073
assert "Mobile documentation navigation" not in rendered
20652074
assert "<details" not in rendered
20662075
assert "<summary" not in rendered
20672076
assert XY_REPOSITORY_URL in rendered
2068-
assert f"View XY on GitHub - {XY_GITHUB_STARS} stars" in rendered
2069-
assert 'target:"_blank"' in rendered
2070-
assert 'rel:"noopener noreferrer"' in rendered
20712077
assert "XY's initial launch is here" in rendered
20722078
assert "Get started" in rendered
20732079
assert "Reserve your spot" not in rendered

‎docs/app/xy_docs/navbar.py‎

Lines changed: 28 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,10 @@
1010
from reflex_site_shared.views.sidebar import navbar_sidebar_button
1111

1212
XY_REPOSITORY_URL = "https://github.com/reflex-dev/xy"
13-
XY_GITHUB_STARS = 5
1413

15-
_REFLEX_NAV_LINKS = (
16-
("Overview", "/docs/"),
17-
("Build with AI", "/docs/ai/overview/best-practices/"),
18-
("Framework", "/docs/getting-started/introduction/"),
19-
("Cloud", "/docs/hosting/deploy-quick-start/"),
14+
_XY_NAV_LINKS = (
15+
("Overview", "/docs/xy/"),
16+
("Reflex Integration", "/docs/xy/integrations/reflex/"),
2017
)
2118

2219

@@ -62,37 +59,47 @@ def xy_docs_logo() -> rx.Component:
6259
)
6360

6461

65-
def _menu_item(label: str, href: str, *, active: bool = False) -> rx.Component:
62+
def _menu_item(label: str, href: str) -> rx.Component:
6663
"""Render one desktop navbar item with the official treatment.
6764
6865
Args:
6966
label: Visible item label.
7067
href: Destination URL.
71-
active: Whether to render the active section underline.
7268
7369
Returns:
7470
Official-style navigation menu item.
7571
"""
76-
active_class = (
77-
"shadow-[inset_0_-1px_0_0_var(--primary-10)] "
78-
"[&_button]:text-primary-10 [&_div]:text-primary-10"
79-
if active
80-
else ""
81-
)
8272
return ui.navigation_menu.item(
8373
rx.el.elements.a(
8474
button(label, size="sm", variant="ghost", native_button=False),
8575
href=href,
8676
class_name="no-underline",
8777
),
88-
class_name=ui.cn(
89-
"hidden h-full items-center justify-center md:flex",
90-
active_class,
91-
),
78+
class_name="hidden h-full items-center justify-center md:flex",
9279
custom_attrs={"role": "menuitem"},
9380
)
9481

9582

83+
def _github_button() -> rx.Component:
84+
"""Render the external XY repository link."""
85+
label = "View XY on GitHub"
86+
return rx.el.elements.a(
87+
button(
88+
get_icon(icon="github_navbar", class_name="size-4 shrink-0"),
89+
"GitHub",
90+
custom_attrs={"aria-label": label},
91+
size="sm",
92+
variant="primary",
93+
native_button=False,
94+
class_name="whitespace-nowrap",
95+
),
96+
href=XY_REPOSITORY_URL,
97+
target="_blank",
98+
rel="noopener noreferrer",
99+
aria_label=label,
100+
)
101+
102+
96103
def _navigation_menu() -> rx.Component:
97104
"""Render the official desktop controls and mobile drawer trigger.
98105
@@ -101,8 +108,7 @@ def _navigation_menu() -> rx.Component:
101108
"""
102109
return ui.navigation_menu.root(
103110
ui.navigation_menu.list(
104-
*(_menu_item(label, href) for label, href in _REFLEX_NAV_LINKS),
105-
_menu_item("XY", "/docs/xy/", active=True),
111+
*(_menu_item(label, href) for label, href in _XY_NAV_LINKS),
106112
class_name="m-0 flex h-full list-none flex-row items-center gap-2",
107113
custom_attrs={"role": "menubar"},
108114
),
@@ -113,23 +119,9 @@ def _navigation_menu() -> rx.Component:
113119
custom_attrs={"role": "menuitem"},
114120
),
115121
ui.navigation_menu.item(
116-
rx.el.elements.a(
117-
button(
118-
get_icon(icon="github_navbar", class_name="size-4 shrink-0"),
119-
str(XY_GITHUB_STARS),
120-
custom_attrs={
121-
"aria-label": (f"View XY on GitHub - {XY_GITHUB_STARS} stars")
122-
},
123-
size="sm",
124-
variant="ghost",
125-
),
126-
href=XY_REPOSITORY_URL,
127-
target="_blank",
128-
rel="noopener noreferrer",
129-
aria_label=f"View XY on GitHub - {XY_GITHUB_STARS} stars",
130-
),
122+
_github_button(),
131123
unstyled=True,
132-
class_name="hidden xl:flex",
124+
class_name="hidden md:flex",
133125
custom_attrs={"role": "menuitem"},
134126
),
135127
ui.navigation_menu.item(
@@ -281,7 +273,6 @@ def xy_docs_navbar() -> rx.Component:
281273

282274

283275
__all__ = [
284-
"XY_GITHUB_STARS",
285276
"XY_REPOSITORY_URL",
286277
"xy_docs_logo",
287278
"xy_docs_navbar",

‎docs/guides/deployment-recipes.md‎

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -156,20 +156,19 @@ assume the policies will merge into a working configuration. Follow
156156
for the current directives and security tradeoffs, and test the final response
157157
headers rather than only opening the file locally.
158158

159-
## Reflex live applications depend on an unreleased adapter
159+
## Reflex live applications use the published adapter
160160

161161
The [Reflex integration path](/docs/xy/integrations/reflex/) describes fixed,
162162
live-token, and state-backed application tiers, but it depends on the separate
163-
`reflex-xy` adapter. That adapter is experimental and is not currently a
164-
published package, so the integration guide is a preview rather than an
165-
installable production recipe.
166-
167-
Until a released adapter version is available, use core XY's standalone HTML,
168-
PNG, or SVG outputs, or evaluate the adapter from source in a pinned test
169-
environment. Do not place `pip install reflex-xy` in production automation and
170-
assume it resolves from the public package index. When it is released, pin
171-
both `xy` and `reflex-xy`, test their documented compatibility, and then follow
172-
the live deployment boundary in the integration guide.
163+
`reflex-xy` adapter. The adapter is published on PyPI, so install it with
164+
`uv add reflex-xy` or `python -m pip install reflex-xy`. It remains
165+
experimental.
166+
167+
For production automation, commit the resolved uv lockfile or pin compatible
168+
`xy` and `reflex-xy` versions in your requirements, test their documented
169+
compatibility, and follow the live deployment boundary in the integration
170+
guide. Core XY's standalone HTML, PNG, and SVG outputs remain available when a
171+
live Reflex application is not required.
173172

174173
For the capability-level decision, see
175174
[Choosing a runtime and deployment mode](/docs/xy/advanced/runtime-and-deployment/).

‎docs/integrations/reflex.md‎

Lines changed: 4 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -15,32 +15,22 @@ Reflex component. The core `xy` package stays framework-neutral: application
1515
state and events remain in Reflex while XY owns chart data, rendering, and
1616
interaction math.
1717

18-
~~~md alert warning
19-
### Unreleased Adapter
20-
21-
`reflex-xy` is not published on PyPI. The adapter is an opt-in prototype whose
22-
API and event payloads may change before its first release. Install it from the
23-
tagged Git subdirectory below; installing it by package name alone with uv or
24-
pip will not work.
25-
~~~
26-
2718
## Install and Configure
2819

29-
Pair the public `xy` 0.0.1 wheel with the adapter from the matching `v0.0.1`
30-
repository tag. Pinning both sides avoids mixing an unreleased adapter revision
31-
with a different core API:
20+
Install `reflex-xy` from PyPI. It declares compatible `xy` and Reflex
21+
dependencies:
3222

3323
~~~~md tabs
3424
## uv
3525

3626
~~~bash
37-
uv add "xy==0.0.1" "reflex-xy @ git+https://github.com/reflex-dev/xy.git@v0.0.1#subdirectory=python/reflex-xy"
27+
uv add reflex-xy
3828
~~~
3929

4030
## pip
4131

4232
~~~bash
43-
python -m pip install "xy==0.0.1" "reflex-xy @ git+https://github.com/reflex-dev/xy.git@v0.0.1#subdirectory=python/reflex-xy"
33+
python -m pip install reflex-xy
4434
~~~
4535
~~~~
4636

‎docs/overview/installation.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -96,23 +96,23 @@ Rust tooling beyond the commands above.
9696
uv add pyarrow
9797
~~~
9898

99-
- The separate Reflex adapter supports state-backed application charts, but it
100-
is experimental and is not published on PyPI. Opt in by pairing the released
101-
`xy` core with the adapter from the matching `v0.0.1` Git tag. With uv:
99+
- The separate `reflex-xy` adapter supports state-backed application charts
100+
and is published on PyPI. It remains experimental. With uv:
102101

103102
~~~bash
104-
uv add "xy==0.0.1" "reflex-xy @ git+https://github.com/reflex-dev/xy.git@v0.0.1#subdirectory=python/reflex-xy"
103+
uv add reflex-xy
105104
~~~
106105

107106
Or with pip:
108107

109108
~~~bash
110-
python -m pip install "xy==0.0.1" "reflex-xy @ git+https://github.com/reflex-dev/xy.git@v0.0.1#subdirectory=python/reflex-xy"
109+
python -m pip install reflex-xy
111110
~~~
112111

113-
The tag keeps the unreleased adapter aligned with the public 0.0.1 core.
114-
Continue with the [Reflex integration guide](/docs/xy/integrations/reflex/)
115-
for its current limitations and setup.
112+
The adapter installs compatible `xy` and Reflex dependencies. Pin resolved
113+
versions for production deployments. Continue with the
114+
[Reflex integration guide](/docs/xy/integrations/reflex/) for its current
115+
limitations and setup.
116116

117117
- Native PNG is the default static raster path and does not launch a browser.
118118
Chromium-based PNG export is optional and discovers Chrome, Chromium, Edge,

‎pr-assets/xy-navbar.jpg‎

110 KB
Loading

0 commit comments

Comments
 (0)