🧪 TESTS: Add tests for syntax snippets

.github/workflows/ci.yml

@@ -46,14 +46,14 @@ jobs:
     - name: Run pytest
       run: |
         pytest --cov=sphinx_design --cov-report=xml --cov-report=term-missing
-    # - name: Upload to Codecov
-    #   if: matrix.python-version == 3.8
-    #   uses: codecov/codecov-action@v1
-    #   with:
-    #     name: pytests
-    #     flags: pytests
-    #     file: ./coverage.xml
-    #     fail_ci_if_error: true
+    - name: Upload to Codecov
+      if: matrix.python-version == '3.8' && matrix.os == 'ubuntu-latest'
+      uses: codecov/codecov-action@v1
+      with:
+        name: pytests
+        flags: pytests
+        file: ./coverage.xml
+        fail_ci_if_error: true
 
   publish:
 

setup.cfg

@@ -38,7 +38,8 @@ code_style =
 rtd =
     myst-parser~=0.15.0
 testing =
-    pytest~=5.4
+    myst-parser~=0.15.0
+    pytest~=6.2
     pytest-cov
     pytest-regressions
 theme_furo =

tests/conftest.py

@@ -0,0 +1,80 @@
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import pytest
+from docutils import nodes
+from sphinx.testing.path import path as sphinx_path
+from sphinx.testing.util import SphinxTestApp
+
+pytest_plugins = "sphinx.testing.fixtures"
+
+
+class SphinxBuilder:
+    def __init__(self, app: SphinxTestApp, src_path: Path):
+        self.app = app
+        self._src_path = src_path
+
+    @property
+    def src_path(self) -> Path:
+        return self._src_path
+
+    @property
+    def out_path(self) -> Path:
+        return Path(self.app.outdir)
+
+    def build(self, assert_pass=True):
+        self.app.build()
+        if assert_pass:
+            assert self.warnings == "", self.status
+        return self
+
+    @property
+    def status(self):
+        return self.app._status.getvalue()
+
+    @property
+    def warnings(self):
+        return self.app._warning.getvalue()
+
+    def get_doctree(
+        self, docname: str, post_transforms: bool = False
+    ) -> nodes.document:
+        doctree = self.app.env.get_doctree(docname)
+        if post_transforms:
+            self.app.env.apply_post_transforms(doctree, docname)
+        # make source path consistent for test comparisons
+        doctree["source"] = (
+            Path(doctree["source"]).relative_to(self.src_path).as_posix()
+        )
+        if doctree["source"].endswith(".rst"):
+            doctree["source"] = doctree["source"][:-4]
+        elif doctree["source"].endswith(".md"):
+            doctree["source"] = doctree["source"][:-3]
+        # remove mathjax classes added by myst parser
+        if doctree.children and isinstance(doctree.children[0], nodes.section):
+            doctree.children[0]["classes"] = []
+        return doctree
+
+
+@pytest.fixture()
+def sphinx_builder(tmp_path: Path, make_app):
+    def _create_project(
+        buildername: str = "html", conf_kwargs: Optional[Dict[str, Any]] = None
+    ):
+        src_path = tmp_path / "srcdir"
+        src_path.mkdir()
+        conf_kwargs = conf_kwargs or {
+            "extensions": ["myst_parser", "sphinx_design"],
+            "myst_enable_extensions": ["colon_fence"],
+        }
+        content = "\n".join(
+            [f"{key} = {value!r}" for key, value in conf_kwargs.items()]
+        )
+        src_path.joinpath("conf.py").write_text(content, encoding="utf8")
+        app = make_app(
+            srcdir=sphinx_path(os.path.abspath(str(src_path))), buildername=buildername
+        )
+        return SphinxBuilder(app, src_path)
+
+    yield _create_project

tests/test_snippets.py

@@ -0,0 +1,95 @@
+"""Test the documented snippets run correctly, and are the same for both RST and MyST."""
+from pathlib import Path
+from typing import Callable
+
+import pytest
+
+from .conftest import SphinxBuilder
+
+SNIPPETS_PATH = Path(__file__).parent.parent / "docs" / "snippets"
+SNIPPETS_GLOB_RST = list((SNIPPETS_PATH / "rst").glob("[!_]*"))
+SNIPPETS_GLOB_MYST = list((SNIPPETS_PATH / "myst").glob("[!_]*"))
+
+
+@pytest.mark.parametrize(
+    "path",
+    SNIPPETS_GLOB_RST,
+    ids=[path.name[: -len(path.suffix)] for path in SNIPPETS_GLOB_RST],
+)
+def test_snippets_rst(
+    sphinx_builder: Callable[..., SphinxBuilder], path: Path, file_regression
+):
+    """Test snippets written in RestructuredText (before post-transforms)."""
+    builder = sphinx_builder()
+    content = "Heading\n-------" + "\n\n" + path.read_text(encoding="utf8")
+    builder.src_path.joinpath("index.rst").write_text(content, encoding="utf8")
+    builder.build()
+    file_regression.check(
+        builder.get_doctree("index").pformat(),
+        basename=f"snippet_pre_{path.name[:-len(path.suffix)]}",
+        extension=".xml",
+        encoding="utf8",
+    )
+
+
+@pytest.mark.parametrize(
+    "path",
+    SNIPPETS_GLOB_MYST,
+    ids=[path.name[: -len(path.suffix)] for path in SNIPPETS_GLOB_MYST],
+)
+def test_snippets_myst(
+    sphinx_builder: Callable[..., SphinxBuilder], path: Path, file_regression
+):
+    """Test snippets written in MyST Markdown (before post-transforms)."""
+    builder = sphinx_builder()
+    content = "# Heading" + "\n\n\n" + path.read_text(encoding="utf8")
+    builder.src_path.joinpath("index.md").write_text(content, encoding="utf8")
+    builder.build()
+    file_regression.check(
+        builder.get_doctree("index").pformat(),
+        basename=f"snippet_pre_{path.name[:-len(path.suffix)]}",
+        extension=".xml",
+        encoding="utf8",
+    )
+
+
+@pytest.mark.parametrize(
+    "path",
+    SNIPPETS_GLOB_RST,
+    ids=[path.name[: -len(path.suffix)] for path in SNIPPETS_GLOB_RST],
+)
+def test_snippets_rst_post(
+    sphinx_builder: Callable[..., SphinxBuilder], path: Path, file_regression
+):
+    """Test snippets written in RestructuredText (after HTML post-transforms)."""
+    builder = sphinx_builder()
+    content = "Heading\n-------" + "\n\n" + path.read_text(encoding="utf8")
+    builder.src_path.joinpath("index.rst").write_text(content, encoding="utf8")
+    builder.build()
+    file_regression.check(
+        builder.get_doctree("index", post_transforms=True).pformat(),
+        basename=f"snippet_post_{path.name[:-len(path.suffix)]}",
+        extension=".xml",
+        encoding="utf8",
+    )
+
+
+@pytest.mark.parametrize(
+    "path",
+    SNIPPETS_GLOB_MYST,
+    ids=[path.name[: -len(path.suffix)] for path in SNIPPETS_GLOB_MYST],
+)
+def test_snippets_myst_post(
+    sphinx_builder: Callable[..., SphinxBuilder], path: Path, file_regression
+):
+    """Test snippets written in MyST Markdown (after HTML post-transforms)."""
+    builder = sphinx_builder()
+    content = "# Heading" + "\n\n\n" + path.read_text(encoding="utf8")
+    builder.src_path.joinpath("index.md").write_text(content, encoding="utf8")
+    builder.build()
+    file_regression.check(
+        builder.get_doctree("index", post_transforms=True).pformat(),
+        basename=f"snippet_post_{path.name[:-len(path.suffix)]}",
+        extension=".xml",
+        encoding="utf8",
+    )

tests/test_snippets/snippet_post_grid-basic.xml

@@ -0,0 +1,18 @@
+<document source="index">
+    <section ids="heading" names="heading">
+        <title>
+            Heading
+        <container classes="sd-container-fluid sd-sphinx-override sd-mb-4 sd-border" design_component="grid-container" is_div="True">
+            <container classes="sd-row sd-row-cols-1 sd-row-cols-xs-1 sd-row-cols-sm-2 sd-row-cols-md-3 sd-row-cols-lg-4" design_component="grid-row" is_div="True">
+                <container classes="sd-col sd-d-flex" design_component="grid-item" is_div="True">
+                    <paragraph>
+                        A
+                <container classes="sd-col sd-d-flex" design_component="grid-item" is_div="True">
+                    <paragraph>
+                        B
+                <container classes="sd-col sd-d-flex" design_component="grid-item" is_div="True">
+                    <paragraph>
+                        C
+                <container classes="sd-col sd-d-flex" design_component="grid-item" is_div="True">
+                    <paragraph>
+                        D

tests/test_snippets/snippet_post_grid-card-columns.xml

@@ -0,0 +1,21 @@
+<document source="index">
+    <section ids="heading" names="heading">
+        <title>
+            Heading
+        <container classes="sd-container-fluid sd-sphinx-override sd-mb-4" design_component="grid-container" is_div="True">
+            <container classes="sd-row sd-row-cols-2 sd-row-cols-xs-2 sd-row-cols-sm-2 sd-row-cols-md-2 sd-row-cols-lg-2" design_component="grid-row" is_div="True">
+                <container classes="sd-col sd-d-flex sd-col-auto sd-col-xs-auto sd-col-sm-auto sd-col-md-auto sd-col-lg-auto" design_component="grid-item" is_div="True">
+                    <container classes="sd-card sd-sphinx-override sd-w-100 sd-shadow" design_component="card" is_div="True">
+                        <container classes="sd-card-body" design_component="card-body" is_div="True">
+                            <paragraph classes="sd-card-text">
+                                A
+                <container classes="sd-col sd-d-flex sd-col-12 sd-col-xs-12 sd-col-sm-6 sd-col-md-6 sd-col-lg-6" design_component="grid-item" is_div="True">
+                    <container classes="sd-card sd-sphinx-override sd-w-100 sd-shadow" design_component="card" is_div="True">
+                        <container classes="sd-card-body" design_component="card-body" is_div="True">
+                            <paragraph classes="sd-card-text">
+                                B
+                <container classes="sd-col sd-d-flex sd-col-12 sd-col-xs-12 sd-col-sm-12 sd-col-md-12 sd-col-lg-12" design_component="grid-item" is_div="True">
+                    <container classes="sd-card sd-sphinx-override sd-w-100 sd-shadow" design_component="card" is_div="True">
+                        <container classes="sd-card-body" design_component="card-body" is_div="True">
+                            <paragraph classes="sd-card-text">
+                                C

tests/test_snippets/snippet_post_grid-card.xml

@@ -0,0 +1,20 @@
+<document source="index">
+    <section ids="heading" names="heading">
+        <title>
+            Heading
+        <container classes="sd-container-fluid sd-sphinx-override sd-mb-4" design_component="grid-container" is_div="True">
+            <container classes="sd-row sd-row-cols-2 sd-row-cols-xs-2 sd-row-cols-sm-2 sd-row-cols-md-2 sd-row-cols-lg-2" design_component="grid-row" is_div="True">
+                <container classes="sd-col sd-d-flex" design_component="grid-item" is_div="True">
+                    <container classes="sd-card sd-sphinx-override sd-w-100 sd-shadow" design_component="card" is_div="True">
+                        <container classes="sd-card-body" design_component="card-body" is_div="True">
+                            <container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
+                                Title 1
+                            <paragraph classes="sd-card-text">
+                                A
+                <container classes="sd-col sd-d-flex" design_component="grid-item" is_div="True">
+                    <container classes="sd-card sd-sphinx-override sd-w-100 sd-shadow" design_component="card" is_div="True">
+                        <container classes="sd-card-body" design_component="card-body" is_div="True">
+                            <container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
+                                Title 2
+                            <paragraph classes="sd-card-text">
+                                B

tests/test_snippets/snippet_post_grid-gutter.xml

@@ -0,0 +1,28 @@
+<document source="index">
+    <section ids="heading" names="heading">
+        <title>
+            Heading
+        <container classes="sd-container-fluid sd-sphinx-override sd-mb-4" design_component="grid-container" is_div="True">
+            <container classes="sd-row sd-row-cols-2 sd-row-cols-xs-2 sd-row-cols-sm-2 sd-row-cols-md-2 sd-row-cols-lg-2 sd-g-1 sd-g-xs-1 sd-g-sm-1 sd-g-md-1 sd-g-lg-1" design_component="grid-row" is_div="True">
+                <container classes="sd-col sd-d-flex" design_component="grid-item" is_div="True">
+                    <container classes="sd-card sd-sphinx-override sd-w-100 sd-shadow" design_component="card" is_div="True">
+                        <container classes="sd-card-body" design_component="card-body" is_div="True">
+                            <paragraph classes="sd-card-text">
+                                A
+                <container classes="sd-col sd-d-flex" design_component="grid-item" is_div="True">
+                    <container classes="sd-card sd-sphinx-override sd-w-100 sd-shadow" design_component="card" is_div="True">
+                        <container classes="sd-card-body" design_component="card-body" is_div="True">
+                            <paragraph classes="sd-card-text">
+                                B
+        <container classes="sd-container-fluid sd-sphinx-override sd-mb-4" design_component="grid-container" is_div="True">
+            <container classes="sd-row sd-row-cols-2 sd-row-cols-xs-2 sd-row-cols-sm-2 sd-row-cols-md-2 sd-row-cols-lg-2 sd-g-3 sd-g-xs-3 sd-g-sm-3 sd-g-md-4 sd-g-lg-5" design_component="grid-row" is_div="True">
+                <container classes="sd-col sd-d-flex" design_component="grid-item" is_div="True">
+                    <container classes="sd-card sd-sphinx-override sd-w-100 sd-shadow" design_component="card" is_div="True">
+                        <container classes="sd-card-body" design_component="card-body" is_div="True">
+                            <paragraph classes="sd-card-text">
+                                A
+                <container classes="sd-col sd-d-flex" design_component="grid-item" is_div="True">
+                    <container classes="sd-card sd-sphinx-override sd-w-100 sd-shadow" design_component="card" is_div="True">
+                        <container classes="sd-card-body" design_component="card-body" is_div="True">
+                            <paragraph classes="sd-card-text">
+                                B

tests/test_snippets/snippet_post_grid-nested.xml

@@ -0,0 +1,49 @@
+<document source="index">
+    <section ids="heading" names="heading">
+        <title>
+            Heading
+        <container classes="sd-container-fluid sd-sphinx-override sd-mb-4" design_component="grid-container" is_div="True">
+            <container classes="sd-row sd-row-cols-1 sd-row-cols-xs-1 sd-row-cols-sm-1 sd-row-cols-md-2 sd-row-cols-lg-2 sd-g-1 sd-g-xs-1 sd-g-sm-1 sd-g-md-1 sd-g-lg-1" design_component="grid-row" is_div="True">
+                <container classes="sd-col sd-d-flex" design_component="grid-item" is_div="True">
+                    <container classes="sd-container-fluid sd-sphinx-override sd-mb-4" design_component="grid-container" is_div="True">
+                        <container classes="sd-row sd-row-cols-1 sd-row-cols-xs-1 sd-row-cols-sm-1 sd-row-cols-md-1 sd-row-cols-lg-1 sd-g-1 sd-g-xs-1 sd-g-sm-1 sd-g-md-1 sd-g-lg-1" design_component="grid-row" is_div="True">
+                            <container classes="sd-col sd-d-flex" design_component="grid-item" is_div="True">
+                                <container classes="sd-card sd-sphinx-override sd-w-100 sd-shadow" design_component="card" is_div="True">
+                                    <container classes="sd-card-body" design_component="card-body" is_div="True">
+                                        <container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
+                                            Item 1.1
+                                        <paragraph classes="sd-card-text">
+                                            Multi-line
+                                        <paragraph classes="sd-card-text">
+                                            content
+                            <container classes="sd-col sd-d-flex" design_component="grid-item" is_div="True">
+                                <container classes="sd-card sd-sphinx-override sd-w-100 sd-shadow" design_component="card" is_div="True">
+                                    <container classes="sd-card-body" design_component="card-body" is_div="True">
+                                        <container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
+                                            Item 1.2
+                                        <paragraph classes="sd-card-text">
+                                            Content
+                <container classes="sd-col sd-d-flex" design_component="grid-item" is_div="True">
+                    <container classes="sd-container-fluid sd-sphinx-override sd-mb-4" design_component="grid-container" is_div="True">
+                        <container classes="sd-row sd-row-cols-1 sd-row-cols-xs-1 sd-row-cols-sm-1 sd-row-cols-md-1 sd-row-cols-lg-1 sd-g-1 sd-g-xs-1 sd-g-sm-1 sd-g-md-1 sd-g-lg-1" design_component="grid-row" is_div="True">
+                            <container classes="sd-col sd-d-flex" design_component="grid-item" is_div="True">
+                                <container classes="sd-card sd-sphinx-override sd-w-100 sd-shadow" design_component="card" is_div="True">
+                                    <container classes="sd-card-body" design_component="card-body" is_div="True">
+                                        <container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
+                                            Item 2.1
+                                        <paragraph classes="sd-card-text">
+                                            Content
+                            <container classes="sd-col sd-d-flex" design_component="grid-item" is_div="True">
+                                <container classes="sd-card sd-sphinx-override sd-w-100 sd-shadow" design_component="card" is_div="True">
+                                    <container classes="sd-card-body" design_component="card-body" is_div="True">
+                                        <container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
+                                            Item 2.2
+                                        <paragraph classes="sd-card-text">
+                                            Content
+                            <container classes="sd-col sd-d-flex" design_component="grid-item" is_div="True">
+                                <container classes="sd-card sd-sphinx-override sd-w-100 sd-shadow" design_component="card" is_div="True">
+                                    <container classes="sd-card-body" design_component="card-body" is_div="True">
+                                        <container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
+                                            Item 2.3
+                                        <paragraph classes="sd-card-text">
+                                            Content

tests/test_snippets/snippet_pre_article-info.xml

@@ -0,0 +1,13 @@
+<document source="index">
+    <section ids="heading" names="heading">
+        <title>
+            Heading
+        <paragraph>
+            <literal>
+                `{article-info}
+                :avatar: images/mugshot.jpeg
+                :avatar-link: https://github.com/chrisjsewell
+                :author: "[Chris Sewell](https://github.com/chrisjsewell)"
+                :date: "{sub-ref}`today`"
+                :read-time: "{sub-ref}`wordcount-minutes` min read"
+                `