Improved component landing page (#687)

* Update code-example parser

* Updated component overview page

* Update component landing page language

* Fix bug in R snippet

* Add test

Author: tcbegley

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(

docs/components_page/components/index.md

@@ -3,19 +3,25 @@ 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.
 
-{{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 to the app's layout.
+4. 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 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}}
+
+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/).

docs/components_page/components/index/simple.R

@@ -1,10 +1,23 @@
+# 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 to the app's layout
+# First we copy the snippet from the docs
+badge <- dbcButton(
+  list(
+    "Notifications",
+    dbcBadge("4", color = "light", text_color = "primary", className = "ms-1")
   ),
-  color = "info"
+  color = "primary"
 )
+
+# 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(port = 8050)

docs/components_page/components/index/simple.jl

@@ -1,7 +1,22 @@
-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 to the app's layout
+# First we copy the snippet from the docs
+badge = dbc_button(
+    [
+        "Notifications",
+        dbc_badge("4", color = "light", text_color = "primary", className = "ms-1"),
+    ],
+    color = "primary",
 )
+
+# 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", 8050)

docs/components_page/components/index/simple.py

@@ -1,7 +1,24 @@
+# 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 to the app's layout
+# First we copy the snippet from the docs
+badge = dbc.Button(
+    [
+        "Notifications",
+        dbc.Badge("4", color="light", text_color="primary", className="ms-1"),
+    ],
+    color="primary",
 )
+
+# 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__":
+    app.run_server()

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.
 

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,
     )
 
 

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",
     )