Merge branch 'main' of https://github.com/facultyai/dash-bootstrap-components into carousel

Author: ann-marie-ward

.github/workflows/doctest.yml

@@ -0,0 +1,61 @@
+name: Test doc snippets
+
+on:
+  push:
+    paths:
+      - docs/components_page/**
+  pull_request:
+    paths:
+      - docs/components_page/**
+
+jobs:
+  build-and-test:
+    name: Build package and test snippets
+    runs-on: 'ubuntu-latest'
+    services:
+      hub:
+        image: selenium/hub:3.141.59-gold
+      firefox:
+        image: selenium/node-chrome:3.141.59-gold
+        env:
+          HUB_HOST: hub
+          HUB_PORT: 4444
+    steps:
+      - uses: actions/checkout@v1
+      - name: Use Node.js 12
+        uses: actions/setup-node@v1
+        with:
+          node-version: 12.x
+      - name: Install dependencies
+        run: npm ci
+      - name: Set up Python 3.8
+        uses: actions/setup-python@v1
+        with:
+          python-version: 3.8
+      - name: Install Dash
+        run: python -m pip install -r requirements-dev.txt
+      - name: Build dash-bootstrap-components
+        run: npm run build
+      - name: Install R dependencies from cran2deb4ubuntu
+        run: |
+          sudo add-apt-repository ppa:c2d4u.team/c2d4u4.0+
+          sudo apt-get update
+          sudo apt-get install r-recommended r-cran-dash
+      - name: Install R package
+        run: sudo R CMD INSTALL .
+      - name: Setup Julia
+        uses: julia-actions/setup-julia@v1
+        with:
+          version: '1.6.1'
+      - name: Add Julia artifacts to repo for local install
+        run: |
+          git add -f deps src/*.jl Project.toml
+          git -c user.name="GitHub Actions" -c user.email="actions@github.com" commit -m "Add Julia build artifacts"
+      - name: Install Julia dependencies
+        run: julia -e 'using Pkg; Pkg.add(["Dash", "DashCoreComponents", "DashHtmlComponents", "HTTP"]); Pkg.add(path=".");'
+      - name: Test Julia installation
+        run: julia -e 'using Dash, DashBootstrapComponents, HTTP;'
+      - name: Install nox
+        run: python3.8 -m pip install -U nox
+      - name: Test R and Julia docs snippets
+        run: nox -s doctest

docs/components_page/__init__.py

@@ -16,7 +16,7 @@
 COMPONENTS = HERE / "components"
 TEMPLATES = HERE.parent / "templates"
 
-LOREM = (COMPONENTS / "modal" / "lorem.txt").read_text()
+LOREM = (COMPONENTS / "modal" / "lorem.txt").read_text().strip()
 
 HIGHLIGHT_JS_CSS = (
     "https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@9.13.1/"

docs/components_page/api_doc.py

@@ -0,0 +1,49 @@
+from pathlib import Path
+
+
+def py_source_to_app(py_source, env):
+    """
+    Create a Dash app from a string defining the app.
+    """
+    env = env or {}
+    exec(py_source, env)
+    return env["app"]
+
+
+def drop_keys(d):
+    """
+    Layout payload for R and Julia apps has a slightly different structure. We
+    drop some keys for parity.
+    """
+    if isinstance(d, dict):
+        return {
+            k: drop_keys(v)
+            for k, v in d.items()
+            if k not in ["propNames", "package"]
+            and v is not None
+            and not (k == "children" and v == "")
+        }
+    elif isinstance(d, list):
+        return [drop_keys(x) for x in d]
+    return d
+
+
+def clean_path(path):
+    if path.startswith("components/"):
+        path = path[11:]
+    return Path(path)
+
+
+def rename_variable(snippet_path, suffix, variable, assign_op="="):
+    with snippet_path.open() as f:
+        lines = f.read().split("\n")
+
+    new_lines = []
+    for line in lines:
+        if line.startswith(f"{variable} {assign_op}"):
+            line = line.replace(
+                f"{variable} {assign_op}", f"{variable}_{suffix} {assign_op}"
+            )
+        new_lines.append(line)
+
+    return "\n".join(new_lines)

docs/components_page/components/__tests__/__init__.py

@@ -0,0 +1,144 @@
+"""
+Automated testing of non-Python code snippets in the docs
+"""
+import re
+import unittest
+from pathlib import Path
+
+import pytest
+import requests
+from dash.testing.application_runners import JuliaRunner, RRunner
+
+from .helpers import clean_path, drop_keys, py_source_to_app, rename_variable
+from .wrappers import JL_WRAPPER, PY_WRAPPER, R_WRAPPER
+
+HERE = Path(__file__).parent
+
+PATTERN = re.compile(r"{{example:(.*)}}")
+PARAMS = [
+    (
+        path,
+        [match.split(":") for match in PATTERN.findall(path.read_text())],
+    )
+    for path in HERE.parent.glob("*.md")
+]
+
+SKIP = ["components/table/kwargs.py", "components/tabs/active_tab.py"]
+ENVS = {
+    "modal.md": {
+        "LOREM": (HERE.parent / "modal" / "lorem.txt").read_text().strip()
+    }
+}
+
+R_PORT = 8051
+JL_PORT = 8053
+
+
+@pytest.fixture
+def dashr_server():
+    with RRunner() as starter:
+        starter.port = R_PORT
+        yield starter
+
+
+@pytest.fixture
+def dashjl_server():
+    with JuliaRunner() as starter:
+        starter.port = JL_PORT
+        yield starter
+
+
+@pytest.mark.parametrize("config", PARAMS)
+def test_r_snippets(dash_thread_server, dashr_server, config):
+    md_path, data = config
+    env = ENVS.get(md_path.name)
+
+    python_r_compare = []
+
+    # Concatenate all the snippets in the markdown file together
+    for i, (snippet_path, name) in enumerate(data):
+        if snippet_path in SKIP:
+            continue
+
+        snippet_path = HERE.parent / clean_path(snippet_path)
+        py_snippet = rename_variable(snippet_path, i, name)
+
+        r_snippet_path = snippet_path.parent / f"{snippet_path.stem}.R"
+
+        if r_snippet_path.exists():
+            r_snippet = rename_variable(
+                r_snippet_path, i, name, assign_op="<-"
+            )
+            python_r_compare.append((py_snippet, r_snippet, f"{name}_{i}"))
+
+    assert_layouts_equal(
+        python_r_compare,
+        dashr_server,
+        R_WRAPPER,
+        R_PORT,
+        dash_thread_server,
+        env,
+        8050,
+    )
+
+
+@pytest.mark.parametrize("config", PARAMS)
+def test_jl_snippets(dash_thread_server, dashjl_server, config):
+    md_path, data = config
+    env = ENVS.get(md_path.name)
+
+    python_jl_compare = []
+
+    # Concatenate all the snippets in the markdown file together
+    for i, (snippet_path, name) in enumerate(data):
+        if snippet_path in SKIP:
+            continue
+
+        snippet_path = HERE.parent / clean_path(snippet_path)
+        py_snippet = rename_variable(snippet_path, i, name)
+
+        jl_snippet_path = snippet_path.parent / f"{snippet_path.stem}.jl"
+
+        if jl_snippet_path.exists():
+            jl_snippet = rename_variable(jl_snippet_path, i, name)
+            python_jl_compare.append((py_snippet, jl_snippet, f"{name}_{i}"))
+
+    assert_layouts_equal(
+        python_jl_compare,
+        dashjl_server,
+        JL_WRAPPER,
+        JL_PORT,
+        dash_thread_server,
+        env,
+        8052,
+    )
+
+
+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(
+            snippet="\n".join(x[0] for x in compare),
+            components=", ".join(x[2] for x in compare),
+        ),
+        env=py_env,
+    )
+    py_runner.start(app, port=py_port)
+    py_layout = requests.get(f"{py_runner.url}/_dash-layout").json()
+
+    # Get other language snippet layout
+    runner.start(
+        wrapper.format(
+            snippet="\n".join(x[1] for x in compare),
+            components=", ".join(x[2] for x in compare),
+            port=port,
+        )
+    )
+    layout = requests.get(f"{runner.url}/_dash-layout").json()
+
+    # Test layouts match
+    unittest.TestCase().assertDictEqual(
+        drop_keys(py_layout), drop_keys(layout)
+    )

docs/components_page/components/__tests__/helpers.py

@@ -0,0 +1,34 @@
+PY_WRAPPER = """
+import dash
+import dash_bootstrap_components as dbc
+
+app = dash.Dash(external_stylesheets=[dbc.themes.BOOTSTRAP])
+
+{snippet}
+
+app.layout = html.Div([{components}])
+"""
+
+R_WRAPPER = """
+library(dash)
+library(dashBootstrapComponents)
+library(dashHtmlComponents)
+
+app <- Dash$new(external_stylesheets = dbcThemes$BOOTSTRAP)
+
+{snippet}
+
+app$layout(htmlDiv(list({components})))
+app$run_server(port = {port})
+"""
+
+JL_WRAPPER = """
+using Dash, DashBootstrapComponents
+
+app = dash(external_stylesheets=[dbc_themes.BOOTSTRAP]);
+
+{snippet}
+
+app.layout = html_div([{components}]);
+run_server(app, "127.0.0.1", {port});
+"""

docs/components_page/components/__tests__/test_snippets.py

@@ -7,30 +7,30 @@ lead: Provide contextual feedback messages for user actions with the `Alert` com
 
 Set the color of `Alert` using the `color` argument and one of the eight supported contextual color names.
 
-{{example:components/alert/simple.py:alerts}}
+{{example:components/alert/simple.py:simple_alerts}}
 
 ## Link color
 
 The Bootstrap `alert-link` class can be used to color match links inside alerts to the color of the alert.
 
-{{example:components/alert/link.py:alerts}}
+{{example:components/alert/link.py:linked_alerts}}
 
 ## Additional content
 
 Alerts can contain additional HTML elements like headings, paragraphs and dividers.
 
-{{example:components/alert/content.py:alert}}
+{{example:components/alert/content.py:complex_alert}}
 
 ## Dismissing
 
 Set `dismissable=True` to add a dismiss button to the alert which closes the alert on click. You can also use the `is_open` property in callbacks to show or hide the alert. By default the alert appears and disappears with a fade animation. To disable this simply set `fade=False`.
 
-{{example:components/alert/dismiss.py:alert}}
+{{example:components/alert/dismiss.py:dimissable_alert}}
 
 ## Automatic dismissal
 
 You can have your `Alert` components dismiss themselves by using the `duration` keyword argument. Specify a duration in milliseconds after which you would like the `Alert` to dismiss itself when it first becomes visible.
 
-{{example:components/alert/auto_dismiss.py:alert}}
+{{example:components/alert/auto_dismiss.py:auto_dismiss_alert}}
 
 {{apidoc:src/components/Alert.js}}