fix: Don't crash on rebuild in watch mode. (#31)

Removes a block of code from mkdocs_simple_plugin of dubious purpose
  that crashes any time it triggers. All tests pass without.

  Resolves #30.

Reviewed-on: #31
Co-authored-by: Glen Whitney <glen@studioinfinity.org>
Co-committed-by: Glen Whitney <glen@studioinfinity.org>

.drone.yml

@@ -99,5 +99,10 @@ steps:
 # using [twine](https://twine.readthedocs.io). Mostly to jog the developer's
 # memory, when a new release is freshly built, the command to update PyPI is
 # `twine upload dist/*`. Also don't forget to create a fresh release on the
-# repository site as well.
+# repository site as well. Finally, you can manually upload the new doc pages
+# for mkdocs-semiliterate itself so the pages can be served by moving the
+# newly-produced `site` directory to `semiliterate` and then executing
+#
+# `scp -r -i [IDENTITY_FILE] semiliterate [USER]@[SERVER]:/opt/bitnami/apps/wordpress/htdocs`
+#
 ###

mkdocs_semiliterate/plugin.py

@@ -14,6 +14,9 @@ of the `simple` plugin.)
 
 from mkdocs import utils
 from mkdocs.config import config_options
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.structure.files import File, Files
+
 from mkdocs_simple_plugin.semiliterate import (
     Semiliterate, LazyFile, ExtractionPattern, StreamExtract)
 from mkdocs_simple_plugin.simple import (Simple, SimplePath)
@@ -23,6 +26,7 @@ import os
 import re
 import subprocess
 import sys
+import time
 import tempfile
 import yaml
 
@@ -352,12 +356,13 @@ terminate: '^\s*\)'
         saved_includes = self.config['include']
         new_config = super().on_config(config, **kwargs)
         self.config['saved_includes'] = saved_includes
-        cfpath = os.path.dirname(config.config_file_path)
+        curpath = os.path.abspath('.')
         self.custom_dir = None
         for themedir in config['theme'].dirs:
-            common = os.path.commonpath([cfpath, themedir])
-            if common == cfpath:
-                self.custom_dir = os.path.relpath(themedir, cfpath)
+            common = os.path.commonpath(
+                [os.path.abspath('.'), os.path.abspath(themedir)])
+            if common == curpath:
+                self.custom_dir = os.path.relpath(themedir, curpath)
                 newthemedir = os.path.join(
                     self.config['build_dir'], self.custom_dir)
                 utils.log.debug(
@@ -368,7 +373,38 @@ terminate: '^\s*\)'
                 break
         return new_config
 
-    def on_files(self, files, config):
+    # Override rather than extend so that we use Semisimple instead of simple
+    # Note code must track mkdocs_simple_plugin, with the added section for
+    # the custom_dir at the bottom. Also removed a section about removing
+    # files from the docs dir if not merging; it was unclear how it was
+    # supposed to work, and it would crash whenever it triggered anyway.
+    def on_files(self, files: Files, /, *,
+                 config: MkDocsConfig):
+        """Update files based on plugin settings."""
+        # Configure Semisimple
+        semisimple = Semisimple(**self.config)
+
+        # Save paths to add to watch if serving
+        do_copy = self.config["copy"]
+        self.paths = semisimple.build_docs(
+            self.dirty, self.last_build_time, do_copy)
+        self.last_build_time = time.time()
+
+        # Code section from mkdocs_simple_plugin has been CUT FROM HERE
+        # If not merging, remove files that are from the docs dir
+        # End of CUT FROM HERE
+
+        for path in self.paths:
+            file = File(
+                src_dir=os.path.abspath(path.output_root),
+                path=path.output_relpath,
+                dest_dir=config.site_dir,
+                use_directory_urls=config["use_directory_urls"]
+            )
+            if file.src_uri in files.src_uris:
+                files.remove(file)
+            files.append(file)
+
         # If we designated a subdirectory for the theme, ignore files in it
         if self.custom_dir:
             sources = files.src_paths
@@ -379,15 +415,7 @@ terminate: '^\s*\)'
                         + f"from theme directory {self.custom_dir}")
                     files.remove(sources[path])
 
-    def on_pre_build(self, *, config):
-        """Build documentation directory with files according to settings."""
-        semisimple = Semisimple(**self.config)
-
-        # Merge docs
-        if self.config["merge_docs_dir"]:
-            semisimple.merge_docs(self.orig_docs_dir)
-        # Copy all of the valid doc files into build_docs_dir
-        self.paths = semisimple.build_docs()
+        return files
 
 
 class Semisimple(Simple):

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = mkdocs-semiliterate
-version = 0.8.1
+version = 0.8.3
 description = Extension of mkdocs-simple-plugin adding easy content inclusion
 long_description = file: README.md
 long_description_content_type = text/markdown

tests/fixtures/theme-mod-location/README.md

@@ -0,0 +1,3 @@
+# Test of syspath extraction
+
+Hopefully Kilroy magically visited above.

tests/fixtures/theme-mod-location/etc/doc_theme/.base.generator

@@ -0,0 +1,4 @@
+{! "\syspath mkdocs/themes/readthedocs/base.html"
+extract:
+  replace: [ ['([<]body.*$)', '\1\n<p>Kilroy was here.</p>\n'] ]
+!}

tests/fixtures/theme-mod-location/etc/mkdocs.yml

@@ -0,0 +1,15 @@
+site_name: syspath inclusion
+docs_dir: ../refsite # dummy
+site_dir: ../site
+theme:
+  name: readthedocs
+  custom_dir: doc_theme/
+plugins:
+- semiliterate:
+    ignore: [refsite]
+    merge_docs_dir: false
+    include: []
+    semiliterate:
+      - pattern: '[.](base).generator$' # Amend readthedocs theme
+        destination: '\1.html'
+        ensurelines: false

tests/fixtures/theme-mod-location/refsite/404.html.cropped

@@ -0,0 +1,89 @@
+<!DOCTYPE html>
+<html class="writer-html5" lang="en" >
+<head>
+    <meta charset="utf-8" />
+    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>syspath inclusion</title>
+    
+    <!--[if lt IE 9]>
+    <![endif]-->
+</head>
+
+<body class="wy-body-for-nav" role="document">
+<p>Kilroy was here.</p>
+
+  <div class="wy-grid-for-nav">
+    <nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
+    <div class="wy-side-scroll">
+      <div class="wy-side-nav-search">
+          <a href="/." class="icon icon-home"> syspath inclusion
+        </a>
+      </div>
+
+      <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
+              <ul>
+                <li class="toctree-l1"><a class="reference internal" href="/.">Test of syspath extraction</a>
+                </li>
+              </ul>
+      </div>
+    </div>
+    </nav>
+
+    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
+      <nav class="wy-nav-top" role="navigation" aria-label="Mobile navigation menu">
+          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
+          <a href="/.">syspath inclusion</a>
+        
+      </nav>
+      <div class="wy-nav-content">
+        <div class="rst-content"><div role="navigation" aria-label="breadcrumbs navigation">
+  <ul class="wy-breadcrumbs">
+    <li><a href="/." class="icon icon-home" aria-label="Docs"></a></li>
+    <li class="wy-breadcrumbs-aside">
+    </li>
+  </ul>
+  <hr/>
+</div>
+          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
+            <div class="section" itemprop="articleBody">
+              
+
+  <h1 id="404-page-not-found">404</h1>
+
+  <p><strong>Page not found</strong></p>
+
+
+            </div>
+          </div><footer>
+
+  <hr/>
+
+  <div role="contentinfo">
+    <!-- Copyright etc -->
+  </div>
+
+  Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
+</footer>
+          
+        </div>
+      </div>
+
+    </section>
+
+  </div>
+
+  <div class="rst-versions" role="note" aria-label="Versions">
+  <span class="rst-current-version" data-toggle="rst-current-version">
+    
+    
+    
+  </span>
+</div>
+        jQuery(function () {
+            SphinxRtdTheme.Navigation.enable(true);
+        });
+
+</body>
+</html>
+

tests/fixtures/theme-mod-location/refsite/css/theme_extra.css

@@ -0,0 +1,197 @@
+/*
+ * Wrap inline code samples otherwise they shoot of the side and
+ * can't be read at all.
+ *
+ * https://github.com/mkdocs/mkdocs/issues/313
+ * https://github.com/mkdocs/mkdocs/issues/233
+ * https://github.com/mkdocs/mkdocs/issues/834
+ */
+.rst-content code {
+    white-space: pre-wrap;
+    word-wrap: break-word;
+    padding: 2px 5px;
+}
+
+/**
+ * Make code blocks display as blocks and give them the appropriate
+ * font size and padding.
+ *
+ * https://github.com/mkdocs/mkdocs/issues/855
+ * https://github.com/mkdocs/mkdocs/issues/834
+ * https://github.com/mkdocs/mkdocs/issues/233
+ */
+.rst-content pre code {
+    white-space: pre;
+    word-wrap: normal;
+    display: block;
+    padding: 12px;
+    font-size: 12px;
+}
+
+/**
+ * Fix code colors
+ *
+ * https://github.com/mkdocs/mkdocs/issues/2027
+ */
+.rst-content code {
+    color: #E74C3C;
+}
+
+.rst-content pre code {
+    color: #000;
+    background: #f8f8f8;
+}
+
+/*
+ * Fix link colors when the link text is inline code.
+ *
+ * https://github.com/mkdocs/mkdocs/issues/718
+ */
+a code {
+    color: #2980B9;
+}
+a:hover code {
+    color: #3091d1;
+}
+a:visited code {
+    color: #9B59B6;
+}
+
+/*
+ * The CSS classes from highlight.js seem to clash with the
+ * ReadTheDocs theme causing some code to be incorrectly made
+ * bold and italic.
+ *
+ * https://github.com/mkdocs/mkdocs/issues/411
+ */
+pre .cs, pre .c {
+    font-weight: inherit;
+    font-style: inherit;
+}
+
+/*
+ * Fix some issues with the theme and non-highlighted code
+ * samples. Without and highlighting styles attached the
+ * formatting is broken.
+ *
+ * https://github.com/mkdocs/mkdocs/issues/319
+ */
+.rst-content .no-highlight {
+    display: block;
+    padding: 0.5em;
+    color: #333;
+}
+
+
+/*
+ * Additions specific to the search functionality provided by MkDocs
+ */
+
+.search-results {
+    margin-top: 23px;
+}
+
+.search-results article {
+    border-top: 1px solid #E1E4E5;
+    padding-top: 24px;
+}
+
+.search-results article:first-child {
+    border-top: none;
+}
+
+form .search-query {
+    width: 100%;
+    border-radius: 50px;
+    padding: 6px 12px;
+    border-color: #D1D4D5;
+}
+
+/*
+ * Improve inline code blocks within admonitions.
+ *
+ * https://github.com/mkdocs/mkdocs/issues/656
+ */
+ .rst-content .admonition code {
+    color: #404040;
+    border: 1px solid #c7c9cb;
+    border: 1px solid rgba(0, 0, 0, 0.2);
+    background: #f8fbfd;
+    background: rgba(255, 255, 255, 0.7);
+}
+
+/*
+ * Account for wide tables which go off the side.
+ * Override borders to avoid weirdness on narrow tables.
+ *
+ * https://github.com/mkdocs/mkdocs/issues/834
+ * https://github.com/mkdocs/mkdocs/pull/1034
+ */
+.rst-content .section .docutils {
+    width: 100%;
+    overflow: auto;
+    display: block;
+    border: none;
+}
+
+td, th {
+    border: 1px solid #e1e4e5 !important;
+    border-collapse: collapse;
+}
+
+/*
+ * Without the following amendments, the navigation in the theme will be
+ * slightly cut off. This is due to the fact that the .wy-nav-side has a
+ * padding-bottom of 2em, which must not necessarily align with the font-size of
+ * 90 % on the .rst-current-version container, combined with the padding of 12px
+ * above and below. These amendments fix this in two steps: First, make sure the
+ * .rst-current-version container has a fixed height of 40px, achieved using
+ * line-height, and then applying a padding-bottom of 40px to this container. In
+ * a second step, the items within that container are re-aligned using flexbox.
+ *
+ * https://github.com/mkdocs/mkdocs/issues/2012
+ */
+ .wy-nav-side {
+    padding-bottom: 40px;
+}
+
+/* For section-index only */
+.wy-menu-vertical .current-section p {
+    background-color: #e3e3e3;
+    color: #404040;
+}
+
+/*
+ * The second step of above amendment: Here we make sure the items are aligned
+ * correctly within the .rst-current-version container. Using flexbox, we
+ * achieve it in such a way that it will look like the following:
+ *
+ * [No repo_name]
+ *         Next >>                    // On the first page
+ * << Previous     Next >>            // On all subsequent pages
+ *
+ * [With repo_name]
+ *    <repo_name>        Next >>      // On the first page
+ * <repo_name>  << Previous  Next >>  // On all subsequent pages
+ *
+ * https://github.com/mkdocs/mkdocs/issues/2012
+ */
+.rst-versions .rst-current-version {
+    padding: 0 12px;
+    display: flex;
+    font-size: initial;
+    justify-content: space-between;
+    align-items: center;
+    line-height: 40px;
+}
+
+/*
+ * Please note that this amendment also involves removing certain inline-styles
+ * from the file ./mkdocs/themes/readthedocs/versions.html.
+ *
+ * https://github.com/mkdocs/mkdocs/issues/2012
+ */
+.rst-current-version span {
+    flex: 1;
+    text-align: center;
+}

tests/fixtures/theme-mod-location/refsite/index.html.cropped

@@ -0,0 +1,97 @@
+<!DOCTYPE html>
+<html class="writer-html5" lang="en" >
+<head>
+    <meta charset="utf-8" />
+    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="description" content="None" />
+    <title>syspath inclusion</title>
+    
+        // Current page data
+        var mkdocs_page_name = "Test of syspath extraction";
+        var mkdocs_page_input_path = "README.md";
+        var mkdocs_page_url = null;
+    
+    <!--[if lt IE 9]>
+    <![endif]-->
+</head>
+
+<body class="wy-body-for-nav" role="document">
+<p>Kilroy was here.</p>
+
+  <div class="wy-grid-for-nav">
+    <nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
+    <div class="wy-side-scroll">
+      <div class="wy-side-nav-search">
+          <a href="." class="icon icon-home"> syspath inclusion
+        </a>
+      </div>
+
+      <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
+              <ul class="current">
+                <li class="toctree-l1 current"><a class="reference internal current" href="#">Test of syspath extraction</a>
+    <ul class="current">
+    </ul>
+                </li>
+              </ul>
+      </div>
+    </div>
+    </nav>
+
+    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
+      <nav class="wy-nav-top" role="navigation" aria-label="Mobile navigation menu">
+          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
+          <a href=".">syspath inclusion</a>
+        
+      </nav>
+      <div class="wy-nav-content">
+        <div class="rst-content"><div role="navigation" aria-label="breadcrumbs navigation">
+  <ul class="wy-breadcrumbs">
+    <li><a href="." class="icon icon-home" aria-label="Docs"></a></li>
+      <li class="breadcrumb-item active">Test of syspath extraction</li>
+    <li class="wy-breadcrumbs-aside">
+    </li>
+  </ul>
+  <hr/>
+</div>
+          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
+            <div class="section" itemprop="articleBody">
+              
+                <h1 id="test-of-syspath-extraction">Test of syspath extraction</h1>
+<p>Hopefully Kilroy magically visited above.</p>
+              
+            </div>
+          </div><footer>
+
+  <hr/>
+
+  <div role="contentinfo">
+    <!-- Copyright etc -->
+  </div>
+
+  Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
+</footer>
+          
+        </div>
+      </div>
+
+    </section>
+
+  </div>
+
+  <div class="rst-versions" role="note" aria-label="Versions">
+  <span class="rst-current-version" data-toggle="rst-current-version">
+    
+    
+    
+  </span>
+</div>
+        jQuery(function () {
+            SphinxRtdTheme.Navigation.enable(true);
+        });
+
+</body>
+</html>
+
+<!--
+-->
+

tests/sites.bash

@@ -5,7 +5,10 @@ for file in tests/fixtures/*
 do
     echo "Testing $startdir/$file"
     cd "$startdir/$file"
-    mkdocs -v build -s
+    if test -d "$startdir/$file/etc"; then
+        mkdocs -v build --config-file etc/mkdocs.yml -s
+    else mkdocs -v build -s
+    fi
     # unfortunately MkDocs writes the run date in the last few lines of index
     # and has version numbers in some of the scripts that are irrelevant:
     for hml in **/*.html