Use on_files instead of prebuild

.mkdocsignore

@@ -5,3 +5,4 @@ venv
 **/__pycache__
 .git
 *.egg-info
+.cache

.pages

@@ -1,7 +1,10 @@
 nav:
     - About: README.md
-    - Mkdocs Simple: mkdocs_simple_plugin
+    - Mkdocs Simple Generator: mkdocs_simple_plugin/generator
+    - Mkdocs Simple Plugin: mkdocs_simple_plugin/plugin
     - Github Action: action.md
     - Docker: docker
     - Examples: examples
-    - Contributing Guide: CONTRIBUTING.md
+    - Developers:
+        - Package Guide: mkdocs_simple_plugin/
+        - Contributing Guide: CONTRIBUTING.md

.vscode/settings.json

@@ -6,6 +6,7 @@
         "autopep",
         "bdist",
         "codeql",
+        "dedupe",
         "devcontainers",
         "dockerfiles",
         "dockerhub",
@@ -15,6 +16,7 @@
         "endfor",
         "endraw",
         "fontawesome",
+        "gemoji",
         "grepout",
         "htmlproofer",
         "indentless",
@@ -43,6 +45,7 @@
         "superfences",
         "thackston",
         "twemoji",
+        "unwatch",
         "VPNW",
         "yapf",
         "yzhang"

examples/gen_readme.py

@@ -193,6 +193,8 @@ def output_criteria(path):
 
         # cleanup
         os.system(f"rm -rf {folder}/site {folder}/mkdocs.yml")
+        if os.path.exists(f"{folder}/clean.sh"):
+            os.system(f"./{folder}/clean.sh")
 
 
 def on_startup(*args, **kwargs):

examples/ok-empty/clean.sh

@@ -1,6 +1,8 @@
 #!/bin/bash
 
-rm -rf site/
-rm -rf docs/
-rm -rf docs_/
-rm -f mkdocs.yml
+# Get the directory of the script
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" > /dev/null 2>&1 && pwd)"
+
+rm -rf ${DIR}site/
+rm -rf ${DIR}docs/
+rm -f ${DIR}/mkdocs.yml

examples/ok-mkdocs-docs-merge/README.md

@@ -14,6 +14,7 @@ plugins:
 
 ```
 ok-mkdocs-docs-merge/
+├── clean.sh
 ├── docs/
 │   ├── draft.md
 │   └── index.md

examples/ok-mkdocs-docs-merge/clean.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+# Get the directory of the script
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" > /dev/null 2>&1 && pwd)"
+
+rm ${DIR}/docs/README.md
+rm ${DIR}/docs/test.md

examples/ok-mkdocsignore/README.md

@@ -55,6 +55,7 @@ hello/foo/foo*
 
 ```
 site/
+├── .mkdocsignore
 ├── hello/
 │   ├── foo/
 │   │   └── bar/

mkdocs.yml

@@ -1,5 +1,5 @@
 site_name: athackst/mkdocs-simple-plugin
-docs_dir: /tmp/mkdocs-simple/mkdocs-simple-plugin
+docs_dir: docs
 plugins:
   - simple
   - awesome-pages
@@ -8,6 +8,8 @@ plugins:
   - social
   - mike:
       canonical_version: latest
+  - git-revision-date-localized:
+      fallback_to_build_date: true
 edit_uri: ''
 site_url: https://www.althack.dev/mkdocs-simple-plugin/
 site_dir: site

mkdocs_simple_plugin/README.md

@@ -1,4 +1,4 @@
-# Developing
+# Package Guide
 
 ## Prerequisites
 
@@ -11,7 +11,13 @@
 
 ## Testing
 
-{% include "tests/test.snippet" %}
+{% include "tests/linters.snippet" %}
+
+{% include "tests/unit_tests.snippet" %}
+
+{% include "tests/integration_tests.snippet" %}
+
+{% include "tests/local_tests.snippet" %}
 
 ## VSCode
 

mkdocs_simple_plugin/plugin.py

@@ -88,12 +88,12 @@
 
 """
 import os
-import shutil
 import tempfile
 import time
 import yaml
 
 
+from mkdocs.structure.files import Files, File
 from mkdocs.plugins import BasePlugin
 from mkdocs.config import config_options
 from mkdocs import config as mkdocs_config
@@ -285,56 +285,79 @@ def on_config(self, config, **kwargs):
         config_site_dir = get_config_site_dir(config.config_file_path)
 
         # Set the build docs dir to tmp location if not set by user
-        if not self.config['build_docs_dir']:
+        if not self.config['build_docs_dir'] and self.config['merge_docs_dir']:
+            self.config['build_docs_dir'] = config['docs_dir']
+        else:
             self.config['build_docs_dir'] = self.tmp_build_docs_dir
 
         utils.log.info(
             "mkdocs-simple-plugin: build_docs_dir: %s",
             self.config['build_docs_dir'])
 
-        # Clean out build folder on config
-        if not self.dirty:
-            shutil.rmtree(self.config['build_docs_dir'], ignore_errors=True)
+        # Create build directory
         os.makedirs(self.config['build_docs_dir'], exist_ok=True)
         # Save original docs directory location
         self.orig_docs_dir = config['docs_dir']
-        # Update the docs_dir with our temporary one
-        config['docs_dir'] = self.config['build_docs_dir']
+        # Update the docs_dir with our temporary one if not merging
+        if not self.config['merge_docs_dir']:
+            config['docs_dir'] = self.config['build_docs_dir']
         # Add all markdown extensions to include list
         self.config['include_extensions'] = list(utils.markdown_extensions) + \
             self.config['include_extensions']
 
         # Always ignore the output paths
         self.config["ignore_paths"] = [
-            config_site_dir,
-            config['site_dir'],
-            self.config['build_docs_dir']]
+            os.path.abspath(config_site_dir),
+            os.path.abspath(config['site_dir']),
+            os.path.abspath(self.config['build_docs_dir'])]
+        if self.config['merge_docs_dir']:
+            self.config["ignore_paths"].append(
+                os.path.abspath(config['docs_dir']))
         return config
 
-    def on_pre_build(self, *, config):
-        """Build documentation directory with files according to settings."""
+    def on_files(self, files: Files, *, config):
+        """Update files based on plugin settings."""
         # Configure simple
         simple = Simple(**self.config)
 
-        # Merge docs
-        if self.config["merge_docs_dir"]:
-            simple.merge_docs(self.orig_docs_dir, self.dirty)
-        # Copy all of the valid doc files into build_docs_dir
         # Save paths to add to watch if serving
         self.paths = simple.build_docs(self.dirty, self.last_build_time)
         self.last_build_time = time.time()
 
+        if not self.config["merge_docs_dir"]:
+            # If not merging, remove files that are from the docs dir
+            # pylint: disable=protected-access
+            for file in files._files[:]:
+                if file.abs_src_path.startswith(
+                        os.path.abspath(config['docs_dir'])):
+                    files.remove(file)
+
+        dedupe_files = {}
+        for file in files:
+            dedupe_files[file.abs_dest_path] = file
+
+        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.abs_dest_path in dedupe_files:
+                files.remove(dedupe_files[file.abs_dest_path])
+            files.append(file)
+        return files
+
     def on_serve(self, server, *, config, builder):
         """Add files to watch server."""
-        # watch the original docs/ directory
-        if os.path.exists(self.orig_docs_dir):
-            server.watch(self.orig_docs_dir)
         # don't watch the build directory
-        server.unwatch(self.config["build_docs_dir"])
+        # pylint: disable=protected-access
+        if self.config["build_docs_dir"] in server._watched_paths:
+            server.unwatch(self.config["build_docs_dir"])
 
         # watch all the doc files
         for path in self.paths:
-            server.watch(path)
+            server.watch(path.input_path)
 
         return server
 

mkdocs_simple_plugin/semiliterate.py

@@ -137,7 +137,7 @@ def __init__(
         self._stop_pattern = re.compile(r"stop=[\"']?([^\"']*)[\"']?")
         # /md
 
-    def setup(self, line: str):
+    def setup(self, line: str) -> None:
         """Process input parameters."""
         self._filename = None
         file_match = get_match(self._filename_pattern, line)
@@ -204,16 +204,16 @@ def __init__(self, directory: str, name: str):
         self.file_name = name
         self.file_object = None
 
-    def __eq__(self, other):
+    def __eq__(self, other) -> bool:
         """Check equality if directory and names are the same."""
         return self.file_directory == other.file_directory \
             and self.file_name == other.file_name
 
-    def __str__(self):
+    def __str__(self) -> str:
         """Return the full file path as a string."""
         return os.path.join(self.file_directory, self.file_name)
 
-    def write(self, arg: str):
+    def write(self, arg: str) -> None:
         """Create and write the file, only if not empty."""
         if not arg:
             return
@@ -223,16 +223,15 @@ def write(self, arg: str):
             self.file_object = open(filename, 'w+')
         self.file_object.write(arg)
 
-    def close(self):
+    def close(self) -> str:
         """Finish the file."""
         if self.file_object is not None:
-            utils.log.info(
-                "        ... extracted %s",
-                os.path.join(
-                    self.file_directory,
-                    self.file_name))
+            file = os.path.join(self.file_directory, self.file_name)
+            utils.log.debug("        ... extracted %s", file)
             self.file_object.close()
             self.file_object = None
+            return file
+        return None
 
 
 class StreamExtract:
@@ -252,11 +251,12 @@ def __init__(
         self.terminate = terminate
         self.patterns = patterns
         self.wrote_something = False
+        self.output_files = []
         self.streams = {
             output_stream.file_name: output_stream
         }
 
-    def transcribe(self, text: str):
+    def transcribe(self, text: str) -> None:
         """Write some text and record if something was written."""
         self.output_stream.write(text)
         if text:
@@ -277,12 +277,14 @@ def try_extract_match(
             self.transcribe(get_line(match_object[match_object.lastindex]))
         return True
 
-    def close(self) -> bool:
+    def close(self) -> list:
         """Returns true if something was written"""
-        self.output_stream.close()
-        return self.wrote_something
+        file = self.output_stream.close()
+        if file and self.wrote_something:
+            self.output_files.append(file)
+        return self.output_files
 
-    def set_output_file(self, filename: str):
+    def set_output_file(self, filename: str) -> None:
         """Set output stream from filename."""
         output_stream = self.output_stream
         if filename:
@@ -295,13 +297,13 @@ def set_output_file(self, filename: str):
             self.streams[filename] = output_stream
         self.set_output_stream(output_stream)
 
-    def set_output_stream(self, stream: LazyFile):
+    def set_output_stream(self, stream: LazyFile) -> None:
         """Set the output stream."""
         if self.output_stream != stream:
             self.close()
             self.output_stream = stream
 
-    def extract(self, **kwargs) -> bool:
+    def extract(self, **kwargs) -> list:
         """Extract from file with semiliterate configuration.
 
         Invoke this method to perform the extraction. Returns true if
@@ -337,7 +339,7 @@ def extract(self, **kwargs) -> bool:
             self.extract_line(line, active_pattern)
         return self.close()
 
-    def extract_line(self, line: str, extraction_pattern: re.Pattern):
+    def extract_line(self, line: str, extraction_pattern: re.Pattern) -> None:
         """Copy line to the output stream, applying specified replacements."""
         line = get_line(extraction_pattern.replace_line(line))
         self.transcribe(line)
@@ -420,19 +422,19 @@ def try_extraction(
             from_directory: str,
             from_file: str,
             destination_directory: str,
-            **kwargs) -> bool:
+            **kwargs) -> list:
         """Try to extract documentation from file with name.
 
         Returns True if extraction was successful.
         """
         to_file = self.filename_match(from_file)
         if not to_file:
-            return False
+            return []
         from_file_path = os.path.join(from_directory, from_file)
         try:
             with open(from_file_path) as original_file:
                 utils.log.debug(
-                    "mkdocs-simple-plugin: Scanning %s...", from_file)
+                    "mkdocs-simple-plugin: Scanning %s...", from_file_path)
                 extraction = StreamExtract(
                     input_stream=original_file,
                     output_stream=LazyFile(destination_directory, to_file),
@@ -441,9 +443,10 @@ def try_extraction(
                     **kwargs)
                 return extraction.extract()
         except (UnicodeDecodeError) as error:
-            utils.log.info("mkdocs-simple-plugin: skipping  %s\n %s",
-                           from_file_path, str(error))
+            utils.log.info("mkdocs-simple-plugin: Skipped  %s", from_file_path)
+            utils.log.debug(
+                "mkdocs-simple-plugin: Error details: %s", str(error))
         except (OSError, IOError) as error:
             utils.log.error("mkdocs-simple-plugin: could not build %s\n %s",
                             from_file_path, str(error))
-        return False
+        return []