Raise error when pymdownx.details is enabled with mkdocs-material, see …

…#47 #44

.pre-commit-config.yaml

@@ -23,12 +23,14 @@ repos:
       entry: flake8
       language: system
       types: [python]
-      args: [--max-line-length=120, --docstring-convention=google, "--ignore=D100,D104,D212,D200,E203,W293,D412,W503"]
+      args: [--max-line-length=120, --docstring-convention=google, "--ignore=D100,D103,D104,D212,D200,E203,W293,D412,W503,E501"]
 # D100 requires all Python files (modules) to have a "public" docstring even if all functions within have a docstring.
 # D104 requires __init__ files to have a docstring
 # D212
 # D200 
 # D412 No blank lines allowed between a section header and its content
 # E203
+# E501 line too long (122 > 120 characters)
+# D103 Missing docstring in public function
 # W293 blank line contains whitespace
 # W503 line break before binary operator (for compatibility with black)

mkdocs_print_site_plugin/plugin.py

@@ -6,6 +6,7 @@
 from mkdocs.structure.files import File
 from mkdocs.structure.pages import Page
 from mkdocs.utils import write_file, copy_file, get_relative_url, warning_filter
+from mkdocs.exceptions import ConfigurationError
 
 from mkdocs_print_site_plugin.renderer import Renderer
 from mkdocs_print_site_plugin.utils import get_theme_name
@@ -59,6 +60,17 @@ def on_config(self, config, **kwargs):
             msg += "Please update the 'plugins:' section in your mkdocs.yml"
             logger.warning(msg)
 
+        # There is a bug with mkdocs-material theme and
+        # the pymdownx.details markdown extension. Detect + raise error.
+        # Details: https://github.com/squidfunk/mkdocs-material/issues/2655
+        if "pymdownx.details" in config.get("markdown_extensions", []):
+            if get_theme_name(config) == "material":
+                msg = "[mkdocs-print-site-plugin]: Using 'mkdocs-material' theme with "
+                msg += "the 'pymdownx.details' markdown extension will break printing.\n"
+                msg += "Please remove 'pymdownx.details' or use a different theme."
+                msg += "Details: https://github.com/squidfunk/mkdocs-material/issues/2655."
+                raise ConfigurationError(msg)
+
         # Get abs path to cover_page_template
         self.cover_page_template_path = ""
         if self.config.get("add_cover_page"):

tests/fixtures/projects/with_markdown_ext/mkdocs.yml

@@ -40,7 +40,6 @@ markdown_extensions:
       smart_enable: all
   - pymdownx.caret
   - pymdownx.critic
-  - pymdownx.details
   - pymdownx.emoji:
       emoji_index: !!python/name:materialx.emoji.twemoji
       emoji_generator: !!python/name:materialx.emoji.to_svg

tests/fixtures/projects/with_markdown_ext/mkdocs_details.yml

@@ -0,0 +1,29 @@
+site_name: Test
+
+theme:
+  name: material
+  custom_dir: docs/overrides
+
+plugins:
+  - print-site
+
+nav:
+  - Home: index.md
+  - Two: two.md
+  - Folder:
+    - Subpage: folder/subpage.md
+    - Duplicate_entry: folder/subfolder/nested_file.md
+  - Extensions:
+    - Admonition: extensions/admonition.md
+    - CodeHilite: extensions/codehilite.md
+    - Footnotes: extensions/footnotes.md
+    - Metadata: extensions/metadata.md
+    - Permalinks: extensions/permalinks.md
+    - Folder: folder/subfolder/nested_file.md
+    - PyMdown: extensions/pymdown.md
+  - Images: images.md
+
+
+# This should raise an error
+markdown_extensions:
+  - pymdownx.details

tests/fixtures/projects/with_markdown_ext/mkdocs_diff_cover_page.yml

@@ -42,7 +42,6 @@ markdown_extensions:
       smart_enable: all
   - pymdownx.caret
   - pymdownx.critic
-  - pymdownx.details
   - pymdownx.emoji:
       emoji_index: !!python/name:materialx.emoji.twemoji
       emoji_generator: !!python/name:materialx.emoji.to_svg

tests/fixtures/projects/with_markdown_ext/mkdocs_img2fig.yml

@@ -41,7 +41,6 @@ markdown_extensions:
       smart_enable: all
   - pymdownx.caret
   - pymdownx.critic
-  - pymdownx.details
   - pymdownx.emoji:
       emoji_index: !!python/name:materialx.emoji.twemoji
       emoji_generator: !!python/name:materialx.emoji.to_svg

tests/fixtures/projects/with_markdown_ext/mkdocs_with_toc.yml

@@ -43,7 +43,6 @@ markdown_extensions:
       smart_enable: all
   - pymdownx.caret
   - pymdownx.critic
-  - pymdownx.details
   - pymdownx.emoji:
       emoji_index: !!python/name:materialx.emoji.twemoji
       emoji_generator: !!python/name:materialx.emoji.to_svg

tests/test_building.py

@@ -30,28 +30,27 @@
 
 def setup_clean_mkdocs_folder(mkdocs_yml_path, output_path):
     """
-    Sets up a clean mkdocs directory
-    
+    Sets up a clean mkdocs directory.
+
     outputpath/testproject
     ├── docs/
     └── mkdocs.yml
-    
+
     Args:
         mkdocs_yml_path (Path): Path of mkdocs.yml file to use
         output_path (Path): Path of folder in which to create mkdocs project
-        
+
     Returns:
         testproject_path (Path): Path to test project
     """
-
     assert os.path.exists(mkdocs_yml_path)
 
     testproject_path = output_path / "testproject"
 
     # Create empty 'testproject' folder
     if os.path.exists(str(testproject_path)):
         logging.warning(
-            """This command does not work on windows. 
+            """This command does not work on windows.
         Refactor your test to use setup_clean_mkdocs_folder() only once"""
         )
         shutil.rmtree(str(testproject_path))
@@ -67,31 +66,28 @@ def setup_clean_mkdocs_folder(mkdocs_yml_path, output_path):
 
 def build_docs_setup(testproject_path):
     """
-    Runs the `mkdocs build` command
-    
+    Runs the `mkdocs build` command.
+
     Args:
         testproject_path (Path): Path to test project
-    
+
     Returns:
         command: Object with results of command
     """
-
     cwd = os.getcwd()
     os.chdir(str(testproject_path))
 
     try:
         run = CliRunner().invoke(build_command, catch_exceptions=True)
         os.chdir(cwd)
         return run
-    except:
+    except Exception:
         os.chdir(cwd)
         raise
 
 
 def check_build(tmp_path, project_mkdocs, exit_code=0):
-    tmp_proj = setup_clean_mkdocs_folder(
-        "tests/fixtures/projects/%s" % project_mkdocs, tmp_path
-    )
+    tmp_proj = setup_clean_mkdocs_folder("tests/fixtures/projects/%s" % project_mkdocs, tmp_path)
     result = build_docs_setup(tmp_proj)
 
     msg = "cwd: %s, result: %s, exception: %s, exc_info: %s" % (
@@ -111,7 +107,7 @@ def text_in_page(tmp_proj, page_path, text):
     return re.search(text, contents)
 
 
-#### Tests ####
+# Tests
 
 
 def test_windmill(tmp_path):
@@ -122,9 +118,11 @@ def test_no_toc(tmp_path):
     prj_path = check_build(tmp_path, "basic/mkdocs_no_toc.yml")
 
     # Table of contents should NOT be there
-    assert not text_in_page(
-        prj_path, "print_page/index.html", '<div id="print-page-toc"'
-    )
+    assert not text_in_page(prj_path, "print_page/index.html", '<div id="print-page-toc"')
+
+
+def test_pymdownx_details_enabled(tmp_path):
+    assert check_build(tmp_path, "with_markdown_ext/mkdocs_details.yml", exit_code=1)
 
 
 def test_add_to_nav_works(tmp_path):
@@ -144,9 +142,7 @@ def test_basic_build(tmp_path):
     assert text_in_page(prj_path, "print_page/index.html", '<div id="print-page-toc"')
 
     # Make sure all 3 pages are combined and present
-    assert text_in_page(
-        prj_path, "print_page/index.html", '<h1 id="index-homepage">Homepage'
-    )
+    assert text_in_page(prj_path, "print_page/index.html", '<h1 id="index-homepage">Homepage')
     assert text_in_page(prj_path, "print_page/index.html", '<h1 id="a-a">A<')
     assert text_in_page(prj_path, "print_page/index.html", '<h1 id="z-z">Z')
 
@@ -161,9 +157,7 @@ def test_basic_build2(tmp_path):
     assert text_in_page(prj_path, "print_page.html", '<div id="print-page-toc"')
 
     # Make sure all 3 pages are combined and present
-    assert text_in_page(
-        prj_path, "print_page.html", '<h1 id="index-homepage">Homepage</h1>'
-    )
+    assert text_in_page(prj_path, "print_page.html", '<h1 id="index-homepage">Homepage</h1>')
     assert text_in_page(prj_path, "print_page.html", '<h1 id="a-a">A</h1>')
     assert text_in_page(prj_path, "print_page.html", '<h1 id="z-z">Z</h1>')
 
@@ -175,9 +169,7 @@ def test_basic_build3(tmp_path):
     assert text_in_page(prj_path, "index.html", 'class="nav-link">Print Site</a>')
 
     # Make sure all 3 pages are combined and present
-    assert text_in_page(
-        prj_path, "print_page/index.html", '<h1 id="index-homepage">Homepage</h1>'
-    )
+    assert text_in_page(prj_path, "print_page/index.html", '<h1 id="index-homepage">Homepage</h1>')
     assert text_in_page(prj_path, "print_page/index.html", '<h1 id="a-a">A</h1>')
     assert text_in_page(prj_path, "print_page/index.html", '<h1 id="z-z">Z</h1>')
 
@@ -189,13 +181,11 @@ def test_basic_build4(tmp_path):
     assert text_in_page(
         prj_path,
         "index.html",
-        'href="print_page\/" class="md-nav__link"',
+        'href="print_page/" class="md-nav__link"',
     )
 
     # Make sure all 3 pages are combined and present
-    assert text_in_page(
-        prj_path, "print_page/index.html", '<h1 id="index-homepage">Homepage</h1>'
-    )
+    assert text_in_page(prj_path, "print_page/index.html", '<h1 id="index-homepage">Homepage</h1>')
     assert text_in_page(prj_path, "print_page/index.html", '<h1 id="a-a">A</h1>')
     assert text_in_page(prj_path, "print_page/index.html", '<h1 id="z-z">Z</h1>')
 
@@ -240,8 +230,11 @@ def test_exclude_page(tmp_path):
     assert not text_in_page(prj_path, "print_page/index.html", "rrI1f2gYE8V4")
 
     # Element in page is ignore (basically 'display: none'), should be present with the right class.
-    assert text_in_page(prj_path, "print_page/index.html", '<p class="print-site-plugin-ignore">This paragraph is ignored, this unique code should not be found: V5lI1bUdnUI9</p>')
-
+    assert text_in_page(
+        prj_path,
+        "print_page/index.html",
+        '<p class="print-site-plugin-ignore">This paragraph is ignored, this unique code should not be found: V5lI1bUdnUI9</p>',
+    )
 
 
 def test_basic_build99(tmp_path):
@@ -252,8 +245,6 @@ def test_basic_build99(tmp_path):
     assert text_in_page(prj_path, "index.html", 'class="nav-link">Print Site</a>')
 
     # Make sure all 3 pages are combined and present
-    assert text_in_page(
-        prj_path, "print_page/index.html", '<h1 id="index-homepage">Homepage'
-    )
+    assert text_in_page(prj_path, "print_page/index.html", '<h1 id="index-homepage">Homepage')
     assert text_in_page(prj_path, "print_page/index.html", '<h1 id="a-a">A')
     assert text_in_page(prj_path, "print_page/index.html", '<h1 id="z-z">Z')