From b088617a09abe6dbfe298d6b7c109fedb457fa39 Mon Sep 17 00:00:00 2001 From: tcbegley Date: Sat, 11 Sep 2021 00:07:14 +0100 Subject: [PATCH 1/5] Update code-example parser --- docs/components_page/components/layout.md | 2 +- docs/components_page/helpers.py | 4 ++-- docs/components_page/markdown_parser.py | 21 +++++++++++++++------ 3 files changed, 18 insertions(+), 9 deletions(-) diff --git a/docs/components_page/components/layout.md b/docs/components_page/components/layout.md index fcbb7f8b1..c4b361e8b 100644 --- a/docs/components_page/components/layout.md +++ b/docs/components_page/components/layout.md @@ -82,7 +82,7 @@ You can also control horizontal alignment of columns using the `justify` keyword Sometimes you may wish to use Bootstrap's grid system for specifying the layout of your app, but you don't want the changes Bootstrap makes to the typography, or to load all the additional CSS classes that Bootstrap specifies. In such a situation, you can link only the CSS required for the grid system using the `themes` module. -{{code-example:components/layout/grid_only.py:python}} +{{code-example:components/layout/grid_only.py}} Alternatively download `bootstrap-grid.css` from the [Bootstrap website](https://getbootstrap.com/docs/4.2/getting-started/download/) and place it in your app's `assets/` directory. See the [Plotly Dash documentation](https://dash.plot.ly/external-resources) for details. diff --git a/docs/components_page/helpers.py b/docs/components_page/helpers.py index 4241bf025..b67ace311 100644 --- a/docs/components_page/helpers.py +++ b/docs/components_page/helpers.py @@ -2,7 +2,7 @@ from dash import dcc, html -def HighlightedSource(py_source, r_source, jl_source): +def HighlightedSource(py_source, r_source, jl_source, className="px-3"): return dbc.Tabs( [ dbc.Tab( @@ -17,7 +17,7 @@ def HighlightedSource(py_source, r_source, jl_source): ] if source is not None ], - className="px-3", + className=className, ) diff --git a/docs/components_page/markdown_parser.py b/docs/components_page/markdown_parser.py index c2dddb24d..c7036a740 100644 --- a/docs/components_page/markdown_parser.py +++ b/docs/components_page/markdown_parser.py @@ -5,7 +5,11 @@ import markdown from dash import dcc, html -from .helpers import ExampleContainer, load_source_with_environment +from .helpers import ( + ExampleContainer, + HighlightedSource, + load_source_with_environment, +) __all__ = ["parse"] @@ -91,12 +95,17 @@ def _safe_load_source(source_path, ext): return None -def _parse_code_example(data): - source_path, language = data.split(":") - source = (HERE / source_path).read_text().strip() +def _parse_code_example(filename): + source_path = HERE / filename + py_source = (HERE / source_path).read_text().strip() + r_source = _safe_load_source(source_path, "R") + jl_source = _safe_load_source(source_path, "jl") + return html.Div( - dcc.Markdown(f"```{language}\n{source}\n```"), - className="source-container", + HighlightedSource( + py_source, r_source, jl_source, className="pb-0 card-header" + ), + className="border source-container rounded", ) From b779e80b4bceb0f09c2f4fb7e241f02286ffa766 Mon Sep 17 00:00:00 2001 From: tcbegley Date: Sat, 11 Sep 2021 00:07:24 +0100 Subject: [PATCH 2/5] Updated component overview page --- docs/components_page/components/index.md | 19 ++++++++++----- .../components_page/components/index/simple.R | 23 ++++++++++++++----- .../components/index/simple.jl | 23 +++++++++++++++---- .../components/index/simple.py | 23 +++++++++++++++---- 4 files changed, 67 insertions(+), 21 deletions(-) diff --git a/docs/components_page/components/index.md b/docs/components_page/components/index.md index 2a4a3c90b..b3dfced2c 100644 --- a/docs/components_page/components/index.md +++ b/docs/components_page/components/index.md @@ -7,15 +7,22 @@ The component documentation for _dash-bootstrap-components_ contains many snippe Example snippets for the different components will look something like this, with tabs to switch between R or Julia versions of the examples. -{{example:components/index/simple.py:layout}} +{{example:components/badge/simple.py:badge}} ## Adding the snippets to your app Note that the contents of each snippet **do not by themselves constitute a working app**. We generally omit boilerplate code such as standard imports and instantiation of the app. In the above example you would additionally need to: -1. import Dash -2. create a Dash app instance (making sure to link a Bootstrap stylesheet, see the [themes documentation](/docs/themes/) for details) -3. assign `layout` to the app layout -4. start the Dash server. +1. Import Dash +2. Create a Dash app instance (making sure to link a Bootstrap stylesheet, see the [themes documentation](/docs/themes/) for details) +3. Add the example +4. Assign your app layout +5. Start the Dash server -If any of the above steps are unclear, please take a look at the [Quickstart](/docs/quickstart/) instructions for creating a basic app, the [examples](https://github.com/facultyai/dash-bootstrap-components/tree/main/examples) in our GitHub repository, or refer to the official Dash documentation for [Python](https://dash.plotly.com/), [R](https://dashr.plotly.com/), or [Julia](https://dash-julia.plotly.com/). +For example, a simple application using the example above would look like this: + +{{code-example:components/index/simple.py}} + +There is more detail on this in the [Quickstart](/docs/quickstart/) instructions for creating a basic app. Additionally, the [examples](https://github.com/facultyai/dash-bootstrap-components/tree/main/examples) in our GitHub repository demonstrate how multiple components can be combined to create a feature rich application. + +For more details on Dash in general, please refer to the official Dash documentation for [Python](https://dash.plotly.com/), [R](https://dashr.plotly.com/), or [Julia](https://dash-julia.plotly.com/). diff --git a/docs/components_page/components/index/simple.R b/docs/components_page/components/index/simple.R index d19304adf..63ab71839 100644 --- a/docs/components_page/components/index/simple.R +++ b/docs/components_page/components/index/simple.R @@ -1,10 +1,21 @@ +# 1. Import Dash +library(dash) library(dashBootstrapComponents) -library(dashHtmlComponents) -layout <- dbcAlert( - paste( - "This is an example of a component being used in the wild.", - "Below me, you can find the code used to create me." +# 2. Create a Dash app instance +app <- Dash$new(external_stylesheets = dbcThemes$BOOTSTRAP) + +# 3. Add the example +badge <- dbcButton( + list( + "Notifications", + dbcBadge("4", color = "light", text_color = "primary", className = "ms-1"), ), - color = "info" + color = "primary" ) + +# 4. Assign your layout to the app layout +app$layout(badge) + +# 5. Start the Dash server +app$run_server(showcase = TRUE) diff --git a/docs/components_page/components/index/simple.jl b/docs/components_page/components/index/simple.jl index cce1ef80d..56e71331b 100644 --- a/docs/components_page/components/index/simple.jl +++ b/docs/components_page/components/index/simple.jl @@ -1,7 +1,20 @@ -using DashBootstrapComponents, DashHtmlComponents +# 1. Import Dash +using Dash, DashBootstrapComponents -layout = dbc_alert( - "This is an example of a component being used in the wild. " * - "Below me, you can find the code used to create me.", - color = "info", +# 2. Create a Dash app instance +app = dash(external_stylesheets = [dbc_themes.BOOTSTRAP]) + +# 3. Add the example +badge = dbc_button( + [ + "Notifications", + dbc_badge("4", color = "light", text_color = "primary", className = "ms-1"), + ], + color = "primary", ) + +# 4. Assign your layout to the app layout +app.layout = badge + +# 5. Start the Dash server +run_server(app, "0.0.0.0", 8080) diff --git a/docs/components_page/components/index/simple.py b/docs/components_page/components/index/simple.py index ba872b27c..a076d9d8c 100644 --- a/docs/components_page/components/index/simple.py +++ b/docs/components_page/components/index/simple.py @@ -1,7 +1,22 @@ +# 1. Import Dash +import dash import dash_bootstrap_components as dbc -layout = dbc.Alert( - "This is an example of a component being used in the wild. " - "Below me, you can find the code used to create me.", - color="info", +# 2. Create a Dash app instance +app = dash.Dash(external_stylesheets=[dbc.themes.BOOTSTRAP]) + +# 3. Add the example +badge = dbc.Button( + [ + "Notifications", + dbc.Badge("4", color="light", text_color="primary", className="ms-1"), + ], + color="primary", ) + +# 4. Assign your layout to the app layout +app.layout = badge + +# 5. Start the Dash server +if __name__ == "__main__": + app.run_server() From 330bb2d6bd7c22b7bdd945c35ba82a9631cc468a Mon Sep 17 00:00:00 2001 From: tcbegley Date: Sat, 11 Sep 2021 07:29:58 +0100 Subject: [PATCH 3/5] Update component landing page language --- docs/components_page/components/index.md | 13 ++++++------- docs/components_page/components/index/simple.R | 8 +++++--- docs/components_page/components/index/simple.jl | 8 +++++--- docs/components_page/components/index/simple.py | 8 +++++--- 4 files changed, 21 insertions(+), 16 deletions(-) diff --git a/docs/components_page/components/index.md b/docs/components_page/components/index.md index b3dfced2c..27960fb32 100644 --- a/docs/components_page/components/index.md +++ b/docs/components_page/components/index.md @@ -3,7 +3,7 @@ title: Components lead: Usage examples for all components in dash-bootstrap-components --- -The component documentation for _dash-bootstrap-components_ contains many snippets showing example usage, as well as api documentation for each component explaining the different props that you can set. +The component documentation for _dash-bootstrap-components_ contains many snippets showing example usage, as well as API documentation for each component explaining the different props that you can set. Example snippets for the different components will look something like this, with tabs to switch between R or Julia versions of the examples. @@ -13,13 +13,12 @@ Example snippets for the different components will look something like this, wit Note that the contents of each snippet **do not by themselves constitute a working app**. We generally omit boilerplate code such as standard imports and instantiation of the app. In the above example you would additionally need to: -1. Import Dash -2. Create a Dash app instance (making sure to link a Bootstrap stylesheet, see the [themes documentation](/docs/themes/) for details) -3. Add the example -4. Assign your app layout -5. Start the Dash server +1. Import Dash. +2. Create a Dash app instance (making sure to link a Bootstrap stylesheet, see the [themes documentation](/docs/themes/) for details). +3. Add the example to the app's layout. +4. Start the Dash server. -For example, a simple application using the example above would look like this: +For example, a simple application incorporating example above could look like this, where we wrap the snippet in a container and add it to the layout. {{code-example:components/index/simple.py}} diff --git a/docs/components_page/components/index/simple.R b/docs/components_page/components/index/simple.R index 63ab71839..60e296b8b 100644 --- a/docs/components_page/components/index/simple.R +++ b/docs/components_page/components/index/simple.R @@ -5,7 +5,8 @@ library(dashBootstrapComponents) # 2. Create a Dash app instance app <- Dash$new(external_stylesheets = dbcThemes$BOOTSTRAP) -# 3. Add the example +# 3. Add the example to the app's layout +# First we copy the snippet from the docs badge <- dbcButton( list( "Notifications", @@ -14,8 +15,9 @@ badge <- dbcButton( color = "primary" ) -# 4. Assign your layout to the app layout -app$layout(badge) +# Then we incorporate the snippet into our layout. +# This example keeps it simple and just wraps it in a Container +app$layout(dbcContainer(badge, fluid = TRUE)) # 5. Start the Dash server app$run_server(showcase = TRUE) diff --git a/docs/components_page/components/index/simple.jl b/docs/components_page/components/index/simple.jl index 56e71331b..30b9bd118 100644 --- a/docs/components_page/components/index/simple.jl +++ b/docs/components_page/components/index/simple.jl @@ -4,7 +4,8 @@ using Dash, DashBootstrapComponents # 2. Create a Dash app instance app = dash(external_stylesheets = [dbc_themes.BOOTSTRAP]) -# 3. Add the example +# 3. Add the example to the app's layout +# First we copy the snippet from the docs badge = dbc_button( [ "Notifications", @@ -13,8 +14,9 @@ badge = dbc_button( color = "primary", ) -# 4. Assign your layout to the app layout -app.layout = badge +# Then we incorporate the snippet into our layout. +# This example keeps it simple and just wraps it in a Container +app.layout = dbc_container(badge, fluid = true) # 5. Start the Dash server run_server(app, "0.0.0.0", 8080) diff --git a/docs/components_page/components/index/simple.py b/docs/components_page/components/index/simple.py index a076d9d8c..c2195dd05 100644 --- a/docs/components_page/components/index/simple.py +++ b/docs/components_page/components/index/simple.py @@ -5,7 +5,8 @@ # 2. Create a Dash app instance app = dash.Dash(external_stylesheets=[dbc.themes.BOOTSTRAP]) -# 3. Add the example +# 3. Add the example to the app's layout +# First we copy the snippet from the docs badge = dbc.Button( [ "Notifications", @@ -14,8 +15,9 @@ color="primary", ) -# 4. Assign your layout to the app layout -app.layout = badge +# Then we incorporate the snippet into our layout. +# This example keeps it simple and just wraps it in a Container +app.layout = dbc.Container(badge, fluid=True) # 5. Start the Dash server if __name__ == "__main__": From e086731a44304e16a2e62864e799abdae9f3226d Mon Sep 17 00:00:00 2001 From: tcbegley Date: Sat, 11 Sep 2021 07:32:38 +0100 Subject: [PATCH 4/5] Fix bug in R snippet --- docs/components_page/components/index/simple.R | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/components_page/components/index/simple.R b/docs/components_page/components/index/simple.R index 60e296b8b..7ac050a66 100644 --- a/docs/components_page/components/index/simple.R +++ b/docs/components_page/components/index/simple.R @@ -10,7 +10,7 @@ app <- Dash$new(external_stylesheets = dbcThemes$BOOTSTRAP) badge <- dbcButton( list( "Notifications", - dbcBadge("4", color = "light", text_color = "primary", className = "ms-1"), + dbcBadge("4", color = "light", text_color = "primary", className = "ms-1") ), color = "primary" ) From 07ea5452fa37455d5e544a517f164180345a1269 Mon Sep 17 00:00:00 2001 From: tcbegley Date: Sat, 11 Sep 2021 07:47:41 +0100 Subject: [PATCH 5/5] Add test --- .../components/__tests__/test_snippets.py | 30 ++++++++++++++++++- .../components_page/components/index/simple.R | 2 +- .../components/index/simple.jl | 2 +- 3 files changed, 31 insertions(+), 3 deletions(-) diff --git a/docs/components_page/components/__tests__/test_snippets.py b/docs/components_page/components/__tests__/test_snippets.py index a5e8249e0..fdc979d4b 100644 --- a/docs/components_page/components/__tests__/test_snippets.py +++ b/docs/components_page/components/__tests__/test_snippets.py @@ -120,10 +120,38 @@ def test_jl_snippets(dash_thread_server, dashjl_server, config): ) +def test_landing_page_example(dash_thread_server, dashr_server, dashjl_server): + index_dir = HERE.parent / "index" + py_source = (index_dir / "simple.py").read_text() + r_source = ( + (index_dir / "simple.R").read_text().replace("8050", str(R_PORT)) + ) + jl_source = ( + (index_dir / "simple.jl").read_text().replace("8050", str(JL_PORT)) + ) + + app = py_source_to_app(py_source, {}) + dash_thread_server.start(app, port=8050) + py_layout = requests.get(f"{dash_thread_server.url}/_dash-layout").json() + + dashr_server.start(r_source) + r_layout = requests.get(f"{dashr_server.url}/_dash-layout").json() + + dashjl_server.start(jl_source) + jl_layout = requests.get(f"{dashjl_server.url}/_dash-layout").json() + + # Test layouts match + unittest.TestCase().assertDictEqual( + drop_keys(py_layout), drop_keys(r_layout) + ) + unittest.TestCase().assertDictEqual( + drop_keys(py_layout), drop_keys(jl_layout) + ) + + def assert_layouts_equal( compare, runner, wrapper, port, py_runner, py_env, py_port ): - # Get python snippet layout app = py_source_to_app( PY_WRAPPER.format( diff --git a/docs/components_page/components/index/simple.R b/docs/components_page/components/index/simple.R index 7ac050a66..c8eb95f16 100644 --- a/docs/components_page/components/index/simple.R +++ b/docs/components_page/components/index/simple.R @@ -20,4 +20,4 @@ badge <- dbcButton( app$layout(dbcContainer(badge, fluid = TRUE)) # 5. Start the Dash server -app$run_server(showcase = TRUE) +app$run_server(port = 8050) diff --git a/docs/components_page/components/index/simple.jl b/docs/components_page/components/index/simple.jl index 30b9bd118..77cda2d2d 100644 --- a/docs/components_page/components/index/simple.jl +++ b/docs/components_page/components/index/simple.jl @@ -19,4 +19,4 @@ badge = dbc_button( app.layout = dbc_container(badge, fluid = true) # 5. Start the Dash server -run_server(app, "0.0.0.0", 8080) +run_server(app, "0.0.0.0", 8050)