Skip to content

Commit 977b70e

Browse files
jcheng5gadenbuiecpsievertGordon Shotwellschloerke
authored
Create two different api doc folders, one for Core and one for Express (#1053)
Co-authored-by: Garrick Aden-Buie <[email protected]> Co-authored-by: Carson Sievert <[email protected]> Co-authored-by: Gordon Shotwell <[email protected]> Co-authored-by: Barret Schloerke <[email protected]>
1 parent 6b7935d commit 977b70e

File tree

187 files changed

+1278
-178
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

187 files changed

+1278
-178
lines changed

‎docs/.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,5 @@ _sidebar.yml
55
/.quarto/
66
objects.json
77
site_libs/
8+
_objects_core.json
9+
_objects_express.json

‎docs/Makefile

Lines changed: 30 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -46,12 +46,39 @@ deps: $(PYBIN) ## Install build dependencies
4646
$(PYBIN)/pip install pip --upgrade
4747
$(PYBIN)/pip install -e ..[doc]
4848

49-
quartodoc: $(PYBIN) ## Build qmd files for API docs
49+
quartodoc: quartodoc_build_core quartodoc_build_express quartodoc_post ## Build quartodocs for express and core
50+
51+
## Build interlinks for API docs
52+
quartodoc_interlinks: $(PYBIN)
53+
. $(PYBIN)/activate \
54+
&& quartodoc interlinks
55+
56+
## Build core API docs
57+
quartodoc_build_core: $(PYBIN) quartodoc_interlinks
5058
$(eval export SHINY_ADD_EXAMPLES=true)
5159
$(eval export IN_QUARTODOC=true)
60+
$(eval export SHINY_MODE=core)
61+
. $(PYBIN)/activate \
62+
&& echo "::group::quartodoc build core docs" \
63+
&& quartodoc build --config _quartodoc-core.yml --verbose \
64+
&& mv objects.json _objects_core.json \
65+
&& echo "::endgroup::"
66+
67+
## Build express API docs
68+
quartodoc_build_express: $(PYBIN) quartodoc_interlinks
69+
$(eval export SHINY_ADD_EXAMPLES=true)
70+
$(eval export IN_QUARTODOC=true)
71+
$(eval export SHINY_MODE=express)
72+
. $(PYBIN)/activate \
73+
&& echo "::group::quartodoc build express docs" \
74+
&& quartodoc build --config _quartodoc-express.yml --verbose \
75+
&& mv objects.json _objects_express.json \
76+
&& echo "::endgroup::"
77+
78+
## Clean up after quartodoc build
79+
quartodoc_post: $(PYBIN)
5280
. $(PYBIN)/activate \
53-
&& quartodoc interlinks \
54-
&& quartodoc build --config _quartodoc.yml --verbose
81+
&& python _combine_objects_json.py
5582

5683
site: ## Build website
5784
. $(PYBIN)/activate \

‎docs/_combine_objects_json.py

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
import json
2+
from dataclasses import asdict, dataclass
3+
from typing import Literal, TypedDict
4+
5+
6+
@dataclass
7+
class QuartodocObject:
8+
project: str
9+
version: str
10+
count: int
11+
items: list["QuartodocObjectItem"]
12+
13+
14+
@dataclass
15+
class QuartodocObjectItem:
16+
name: str
17+
domain: str
18+
19+
# function: "shiny.ui.page_sidebar"
20+
# class: "shiny.render.renderer._renderer.Renderer"
21+
# attribute: "shiny.render.renderer._renderer.Renderer.output_id"
22+
role: Literal["function", "class", "attribute", "module"]
23+
priority: str
24+
uri: str
25+
dispname: str
26+
27+
28+
def read_objects_file(path: str) -> QuartodocObject:
29+
with open(path) as file:
30+
content = json.load(file)
31+
items = [QuartodocObjectItem(**item) for item in content.pop("items")]
32+
return QuartodocObject(**content, items=items)
33+
34+
35+
def write_objects_file(objects: QuartodocObject, path: str) -> None:
36+
with open(path, "w") as file:
37+
json.dump(objects, file, indent=4, default=lambda dc: dc.__dict__)
38+
39+
40+
print("\nCombining objects json files...")
41+
objects_core = read_objects_file("_objects_core.json")
42+
objects_express = read_objects_file("_objects_express.json")
43+
44+
items_map: dict[str, QuartodocObjectItem] = {}
45+
46+
for item in [*objects_core.items, *objects_express.items]:
47+
if item.name in items_map:
48+
continue
49+
items_map[item.name] = item
50+
51+
objects_ret = QuartodocObject(
52+
project="shiny",
53+
version="1",
54+
count=len(items_map.values()),
55+
items=[*items_map.values()],
56+
)
57+
58+
59+
print("Core:", objects_core.count)
60+
print("Express:", objects_express.count)
61+
print("Combined:", objects_ret.count)
62+
63+
# Save combined objects file info
64+
write_objects_file(objects_ret, "objects.json")

‎docs/_quarto.yml

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,10 @@ website:
1818
pinned: true
1919
search: true
2020
left:
21-
- text: "API"
22-
file: api/index.qmd
21+
- text: "Express API"
22+
file: api/express/index.qmd
23+
- text: "Core API"
24+
file: api/core/index.qmd
2325
right:
2426
- icon: github
2527
href: https://github.com/posit-dev/py-shiny

‎docs/_quartodoc.yml renamed to ‎docs/_quartodoc-core.yml

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
quartodoc:
22
style: pkgdown
3-
dir: api
3+
dir: api/core
44
out_index: index.qmd
55
package: shiny
66
rewrite_all_pages: false
7-
sidebar: api/_sidebar.yml
7+
sidebar: api/core/_sidebar.yml
88
dynamic: true
99
renderer:
1010
style: _renderer.py
@@ -374,6 +374,7 @@ quartodoc:
374374
- ui.panel_main
375375
- ui.panel_sidebar
376376
- ui.nav
377+
- render.transformer.output_transformer
377378
- render.transformer.resolve_value_fn
378379
- title: Experimental
379380
desc: "These methods are under consideration and are considered unstable. However, if there is a method you are excited about, please let us know!"

‎docs/_quartodoc-express.yml

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
quartodoc:
2+
style: pkgdown
3+
dir: api/express
4+
out_index: index.qmd
5+
package: shiny
6+
rewrite_all_pages: false
7+
sidebar: api/express/_sidebar.yml
8+
dynamic: true
9+
renderer:
10+
style: _renderer.py
11+
show_signature_annotations: false
12+
sections:
13+
- title: Input components
14+
desc: Gather user input.
15+
contents:
16+
- express.ui.input_select
17+
- express.ui.input_selectize
18+
- express.ui.input_slider
19+
- express.ui.input_date
20+
- express.ui.input_date_range
21+
- express.ui.input_checkbox
22+
- express.ui.input_checkbox_group
23+
- express.ui.input_switch
24+
- express.ui.input_radio_buttons
25+
- express.ui.input_numeric
26+
- express.ui.input_text
27+
- express.ui.input_text_area
28+
- express.ui.input_password
29+
- express.ui.input_action_button
30+
- express.ui.input_action_link
31+
- title: Output components
32+
desc: Reactively render output.
33+
contents:
34+
- express.render.plot
35+
- express.render.table
36+
- express.render.DataTable
37+
- express.render.data_frame
38+
- express.render.DataGrid
39+
- express.render.text
40+
- express.render.ui
41+
- express.render.download
42+
- express.render.image
43+
- express.render.express
44+
- title: Layouts and other UI tools
45+
desc: Tools for creating, arranging, and styling UI components.
46+
contents:
47+
- express.ui.page_opts
48+
- express.ui.sidebar
49+
- express.ui.layout_columns
50+
- express.ui.layout_column_wrap
51+
- express.ui.card
52+
- express.ui.card_header
53+
- express.ui.card_footer
54+
- express.ui.value_box
55+
- express.ui.value_box_theme
56+
- express.ui.popover
57+
- express.ui.tooltip
58+
- express.ui.accordion
59+
- express.ui.accordion_panel
60+
- express.ui.layout_sidebar
61+
- title: Navigate multiple panels
62+
desc: Create a set of panels that can be navigated between.
63+
contents:
64+
- express.ui.nav_panel
65+
- express.ui.navset_card_underline
66+
- express.ui.navset_card_tab
67+
- express.ui.navset_card_pill
68+
- express.ui.nav_spacer
69+
- express.ui.nav_menu
70+
- express.ui.nav_control
71+
- express.ui.navset_bar
72+
- express.ui.navset_tab
73+
- express.ui.navset_pill
74+
- express.ui.navset_underline
75+
- express.ui.navset_pill_list
76+
- express.ui.navset_hidden
77+
- title: Reactive programming
78+
desc: Create reactive functions and dependencies.
79+
contents:
80+
- reactive.calc
81+
- reactive.effect
82+
- reactive.value
83+
- reactive.event
84+
- reactive.isolate
85+
- reactive.invalidate_later
86+
- reactive.flush
87+
- reactive.poll
88+
- reactive.file_reader
89+
- reactive.lock
90+
- req
91+
- title: Reusable Express code
92+
desc: Create reusable Express code.
93+
contents:
94+
- express.ui.hold
95+
- express.expressify
96+
- title: Update inputs
97+
desc: Programmatically update input values.
98+
contents:
99+
- name: express.ui.update_select
100+
dynamic: true
101+
- name: express.ui.update_selectize
102+
dynamic: true
103+
- name: express.ui.update_slider
104+
dynamic: true
105+
- ui.update_date
106+
- name: express.ui.update_date_range
107+
dynamic: true
108+
- name: express.ui.update_checkbox
109+
dynamic: true
110+
- name: express.ui.update_checkbox_group
111+
dynamic: true
112+
- name: express.ui.update_switch
113+
dynamic: true
114+
- name: express.ui.update_radio_buttons
115+
dynamic: true
116+
- name: express.ui.update_numeric
117+
dynamic: true
118+
- ui.update_text
119+
- name: express.ui.update_text_area
120+
dynamic: "shiny.ui.update_text"
121+
- name: express.ui.update_navs
122+
dynamic: true
123+
- title: Update UI Layouts
124+
desc: ""
125+
contents:
126+
- express.ui.update_sidebar
127+
- express.ui.update_tooltip
128+
- express.ui.update_popover
129+
- express.ui.update_accordion
130+
- express.ui.update_accordion_panel
131+
- express.ui.insert_accordion_panel
132+
- express.ui.remove_accordion_panel
133+
- title: Display messages
134+
desc: Display messages to the user.
135+
contents:
136+
- express.ui.help_text
137+
- express.ui.notification_show
138+
- express.ui.notification_remove
139+
- express.ui.modal
140+
- express.ui.modal_show
141+
- express.ui.modal_remove
142+
- express.ui.modal_button
143+
- express.ui.Progress # uses class.rst
144+
- title: UI panels
145+
desc: Visually group together a section of UI components.
146+
contents:
147+
- express.ui.panel_absolute
148+
- express.ui.panel_fixed
149+
- express.ui.panel_title
150+
- express.ui.panel_well
151+
- title: Dynamic UI
152+
desc: Dynamically show/hide UI elements.
153+
contents:
154+
- express.ui.panel_conditional
155+
- express.ui.insert_ui
156+
- express.ui.remove_ui
157+
- title: UI as HTML
158+
desc: Tools for creating HTML/CSS/JS
159+
contents:
160+
- express.ui.markdown
161+
- express.ui.include_css
162+
- express.ui.include_js
163+
- express.ui.HTML # uses justattributes.rst template
164+
- name: express.ui.tags # uses tags.rst template
165+
children: embedded
166+
- express.ui.TagList # uses class.rst template
167+
# TODO: should these be included?
168+
# - express.ui.fill.as_fillable_container
169+
# - express.ui.fill.as_fill_item
170+
# - express.ui.fill.remove_all_fill
171+
# - express.ui.css.as_css_unit
172+
# - express.ui.css.as_css_padding
173+
- title: Express developer tooling
174+
desc:
175+
contents:
176+
- express.is_express_app
177+
- express.wrap_express_app

0 commit comments

Comments
 (0)