mkdocs-simple-plugin 3.0.0__tar.gz → 3.2.0__tar.gz

{mkdocs_simple_plugin-3.0.0 → mkdocs_simple_plugin-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: mkdocs-simple-plugin
-Version: 3.0.0
+Version: 3.2.0
 Summary: Plugin for adding simple wiki site creation from markdown files interspersed within your code with MkDocs.
 Project-URL: Documentation, http://www.althack.dev/mkdocs-simple-plugin
 Project-URL: Homepage, http://www.althack.dev/mkdocs-simple-plugin
@@ -15,7 +15,6 @@ Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Information Technology
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
@@ -23,7 +22,7 @@ Classifier: Programming Language :: Python :: 3.11
 Requires-Python: >=3
 Requires-Dist: click>=7.1
 Requires-Dist: markupsafe>=2.1.1
-Requires-Dist: mkdocs>=1.4.0
+Requires-Dist: mkdocs>=1.6.0
 Requires-Dist: pyyaml>=6.0
 Description-Content-Type: text/markdown
 

mkdocs_simple_plugin-3.2.0/mkdocs_simple_plugin/README.md

@@ -0,0 +1,55 @@
+# Package Guide
+
+## Prerequisites
+
+{% include "setup.snippet" %}
+
+## Building
+
+{% include "build.snippet" %}
+
+## Testing
+ 
+{% include "tests/linters.snippet" %}
+
+{% include "tests/unit_tests.snippet" %}
+
+{% include "tests/integration_tests.snippet" %}
+
+{% include "tests/local_tests.snippet" %}
+
+## VSCode
+
+This package includes a preconfigured Visual Studio Code (VSCode) workspace and development container, making it easier to get started with developing your plugin. 
+
+To get started with developing your plugin in VSCode, follow these steps:
+
+1. **Open the project in VSCode** Open VSCode and select the "Open Folder" option from the File menu. Navigate to the location where you've saved the project and select the root folder of the project.
+
+2. **Connect to the development container** VSCode will automatically detect the presence of the development container and prompt you to connect to it. Follow the on-screen instructions to connect to the container.
+
+3. **Run the build task** To build the plugin, you can use the preconfigured build task in VSCode. This task is defined in the `build.sh` file and can be run by using the "Run Build Task" option from the Terminal menu or by using the Ctrl + Shift + B shortcut.
+
+4. **Debug the plugin** You can use the VSCode debugger to inspect the code and debug your plugin. The debugger is configured in the launch.json file and can be started by using the "Start Debugging" option from the Debug menu or by using the F5 key.
+
+For more information on how to use VSCode and Docker for development, please refer to [how I develop with VSCode and Docker](https://allisonthackston.com/articles/docker-development.html) and [how I use VSCode tasks](https://allisonthackston.com/articles/vscode-tasks.html).
+
+## Packaging
+
+The project uses Hatch to build and package the plugin [![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch)
+
+Hatch is a Python packaging tool that helps simplify the process of building and distributing Python packages. It automates many manual steps, such as creating a setup script, creating a distribution package, and uploading the package to a repository, allowing developers to focus on writing code. Hatch is flexible and customizable, with options for specifying dependencies, including additional files, and setting up test suites, and is actively maintained with a growing community of users and contributors.
+
+### Build the package
+
+```bash
+hatch build
+```
+
+### Publish the package
+
+```bash
+hatch publish
+```
+
+Please note that you may need to set up the appropriate credentials for the repository before you can publish the package. If you encounter any issues with publishing the package, please refer to the [Hatch documentation](https://hatch.pypa.io/latest/) for guidance.

{mkdocs_simple_plugin-3.0.0 → mkdocs_simple_plugin-3.2.0}/mkdocs_simple_plugin/generator.py

@@ -68,7 +68,6 @@ def default_config():
     # Set the config variables via environment if exist
     maybe_set_string("site_name")
     maybe_set_string("site_url")
-    maybe_set_string("site_dir")
     maybe_set_string("repo_url")
     maybe_set_dict("theme", "name")
     return config
@@ -86,7 +85,7 @@ def write_config(config_file, config):
     """Write configuration file."""
     if os.path.dirname(config_file):
         os.makedirs(os.path.dirname(config_file), exist_ok=True)
-    with open(config_file, 'w+') as file:
+    with open(config_file, 'w+', encoding="utf-8") as file:
         try:
             yaml.dump(
                 data=config,
@@ -106,7 +105,7 @@ def setup_config(config_file="mkdocs.yml"):
         # from the folder name.
         write_config(config_file, config)
     # Open the config file to verify settings.
-    with open(config_file, 'r') as stream:
+    with open(config_file, 'r', encoding="utf-8") as stream:
         try:
             local_config = yaml.load(stream, yaml.Loader)
             if local_config:

{mkdocs_simple_plugin-3.0.0 → mkdocs_simple_plugin-3.2.0}/mkdocs_simple_plugin/plugin.py

@@ -90,14 +90,16 @@ mkdocs serve
 import os
 import tempfile
 import time
-import yaml
-
+from typing import Callable, Literal
 
-from mkdocs.structure.files import Files, File
-from mkdocs.plugins import BasePlugin
-from mkdocs.config import config_options
+import yaml
 from mkdocs import config as mkdocs_config
 from mkdocs import utils
+from mkdocs.config import config_options
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.livereload import LiveReloadServer
+from mkdocs.plugins import BasePlugin
+from mkdocs.structure.files import File, Files
 
 from mkdocs_simple_plugin.simple import Simple
 
@@ -107,22 +109,48 @@ class SimplePlugin(BasePlugin):
 
     # md file=config_scheme.snippet
     config_scheme = (
-        # ### include_folders
+        # ### include_folders (renamed)
+        #
+        # Renamed [folders](#folders)
+        ('include_folders', config_options.Deprecated(
+            moved_to="folders", removed=False)),
+        #
+        # ### folders
         #
         # Directories whose name matches a glob pattern in this list will be
         # searched for documentation
-        ('include_folders', config_options.Type(list, default=['*'])),
+        ('folders', config_options.Type(list, default=['*'])),
         #
-        # ### ignore_folders
+        # ### ignore_folders (renamed)
+        #
+        # Renamed [ignore](#ignore)
+        ('ignore_folders', config_options.Deprecated(
+            moved_to="ignore", removed=False)),
+        #
+        # ### ignore
         #
         # Directories whose name matches a glob pattern in this list will NOT be
         # searched for documentation.
-        ('ignore_folders', config_options.Type(list, default=[])),
+        ('ignore', config_options.Type(
+            list,
+            default=[
+                "venv",
+                ".cache/**",
+                ".devcontainer/**",
+                ".github/**",
+                ".vscode/**",
+                "**/__pycache__/**",
+                ".git/**",
+                "*.egg-info",
+            ])),
         #
-        # ### ignore_hidden
+        # ### ignore_hidden (deprecated)
         #
         # Hidden directories will not be searched if this is true.
-        ('ignore_hidden', config_options.Type(bool, default=True)),
+        ('ignore_hidden', config_options.Deprecated(
+            moved_to=None,
+            message="Common ignore files have been added to 'ignore' instead",
+            removed=False)),
         #
         # ### merge_docs_dir
         #
@@ -132,17 +160,35 @@ class SimplePlugin(BasePlugin):
         # the result.
         ('merge_docs_dir', config_options.Type(bool, default=True)),
         #
-        # ### build_docs_dir
+        # ### build_docs_dir (renamed)
+        #
+        # Renamed [build_dir](#build_dir)
+        ('build_docs_dir', config_options.Deprecated(
+            moved_to="build_dir", removed=False)),
+        #
+        # ### build_dir
         #
         # If set, the directory where docs will be collated to be build.
         # Otherwise, the build docs directory will be a temporary directory.
-        ('build_docs_dir', config_options.Type(str, default='')),
+        ('build_dir', config_options.Type(str, default='')),
+        #
+        # #### copy
         #
-        # ### include_extensions
+        # If set, docs will be copied to the build_docs_dir.
+        # Otherwise, files will be used in place.
+        ('copy', config_options.Type(bool, default=False)),
+        #
+        # ### include_extensions (renamed)
+        #
+        # Renamed [include](#include)
+        ('include_extensions', config_options.Deprecated(
+            moved_to="include", message="", removed=False)),
+        #
+        # ### include
         #
         # Any file in the searched directories whose name contains a string in
         # this list will simply be copied to the generated documentation.
-        ('include_extensions',
+        ('include',
             config_options.Type(
                 list,
                 default=[
@@ -260,16 +306,21 @@ class SimplePlugin(BasePlugin):
         # PY2 returns a byte string by default. The Unicode prefix ensures a
         # Unicode string is returned. And it makes MkDocs temp dirs easier to
         # identify.
-        self.tmp_build_docs_dir = tempfile.mkdtemp(prefix="mkdocs_simple_")
+        self.tmp_build_dir = tempfile.mkdtemp(prefix="mkdocs_simple_")
         self.paths = None
         self.dirty = False
         self.last_build_time = None
 
-    def on_startup(self, *, command, dirty: bool) -> None:
+    def on_startup(self,
+                   *,
+                   command: Literal['build',
+                                    'gh-deploy',
+                                    'serve'],
+                   dirty: bool):
         """Configure the plugin on startup."""
         self.dirty = dirty
 
-    def on_config(self, config, **kwargs):
+    def on_config(self, config: MkDocsConfig):
         """Update configuration to use a temporary build directory."""
         # Save the config for documentation
         default_config = dict((name, config_option.default)
@@ -285,57 +336,55 @@ class SimplePlugin(BasePlugin):
         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'] and self.config['merge_docs_dir']:
-            self.config['build_docs_dir'] = config['docs_dir']
+        if not self.config['build_dir'] and self.config['merge_docs_dir']:
+            self.config['build_dir'] = config['docs_dir']
         else:
-            self.config['build_docs_dir'] = self.tmp_build_docs_dir
+            self.config['build_dir'] = self.tmp_build_dir
 
         utils.log.info(
-            "mkdocs-simple-plugin: build_docs_dir: %s",
-            self.config['build_docs_dir'])
+            "mkdocs-simple-plugin: build_dir: %s",
+            self.config['build_dir'])
 
         # Create build directory
-        os.makedirs(self.config['build_docs_dir'], exist_ok=True)
+        os.makedirs(self.config['build_dir'], exist_ok=True)
         # Save original docs directory location
         self.orig_docs_dir = config['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']
+            config['docs_dir'] = self.config['build_dir']
         # Add all markdown extensions to include list
-        self.config['include_extensions'] = list(utils.markdown_extensions) + \
-            self.config['include_extensions']
+        self.config['include'] = list(utils.markdown_extensions) + \
+            self.config['include']
 
         # Always ignore the output paths
         self.config["ignore_paths"] = [
             os.path.abspath(config_site_dir),
             os.path.abspath(config['site_dir']),
-            os.path.abspath(self.config['build_docs_dir'])]
+            os.path.abspath(self.config['build_dir'])]
         if self.config['merge_docs_dir']:
             self.config["ignore_paths"].append(
                 os.path.abspath(config['docs_dir']))
         return config
 
-    def on_files(self, files: Files, *, config):
+    def on_files(self, files: Files, /, *,
+                 config: MkDocsConfig):
         """Update files based on plugin settings."""
         # Configure simple
         simple = Simple(**self.config)
 
         # Save paths to add to watch if serving
-        self.paths = simple.build_docs(self.dirty, self.last_build_time)
+        do_copy = self.config["copy"]
+        self.paths = simple.build_docs(
+            self.dirty, self.last_build_time, do_copy)
         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'])):
+            abs_docs_dir = os.path.abspath(config['docs_dir'])
+            for _, file in files.src_uris.items():
+                if file.abs_src_path.startswith(abs_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),
@@ -343,17 +392,18 @@ class SimplePlugin(BasePlugin):
                 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])
+            if file.src_uri in files.src_uris:
+                files.remove(file)
             files.append(file)
         return files
 
-    def on_serve(self, server, *, config, builder):
+    def on_serve(self, server: LiveReloadServer, /, *, config: MkDocsConfig,
+                 builder: Callable):
         """Add files to watch server."""
         # don't watch the build directory
         # pylint: disable=protected-access
-        if self.config["build_docs_dir"] in server._watched_paths:
-            server.unwatch(self.config["build_docs_dir"])
+        if self.config["build_dir"] in server._watched_paths:
+            server.unwatch(self.config["build_dir"])
 
         # watch all the doc files
         for path in self.paths:

{mkdocs_simple_plugin-3.0.0 → mkdocs_simple_plugin-3.2.0}/mkdocs_simple_plugin/semiliterate.py

@@ -1,24 +1,72 @@
 """Semiliterate module handles document extraction from source files."""
+from io import TextIOWrapper
 import os
 import re
 
-from mkdocs import utils
-
+from dataclasses import dataclass
 
-def get_line(line: str) -> str:
-    """Returns line with EOL."""
-    if not line:
-        return None
-    return line if line.endswith("\n") else line + '\n'
+from mkdocs import utils
 
 
-def get_match(pattern: re.Pattern, line: str) -> re.Match:
+def _get_match(pattern: re.Pattern, line: str) -> re.Match:
     """Returns the match for the given pattern."""
     if not pattern:
         return None
     return pattern.search(line)
 
 
+@dataclass
+class InlineParams:
+    """Inline parameters for extraction."""
+    # md file=inline_params.snippet
+    # These parameters should be on the same line as the start block.
+    #
+    # For example:
+    #
+    # ```
+    #  /**md file="new_name.md" trim=2 content="^\s*\/\/\s?(.*)$"
+    # ```
+    #
+    # #### Set output file name
+    #
+    #  Filename is relative to the folder of the file being processed.
+    #
+    # ```
+    # file=<name>
+    # ```
+    filename_pattern: re.Pattern = re.compile(r"file=[\"']?(\w+.\w+)[\"']?\b")
+    filename: str = None
+    #
+    # #### Trim the front of a line
+    #
+    # Useful for removing leading spaces.
+    #
+    # ```
+    # trim=#
+    # ```
+    trim_pattern: re.Pattern = re.compile(r"trim=[\"']?(\d+)[\"']?\b")
+    trim: int = 0
+    # #### Capture content
+    #
+    # Regex expression to capture content, otherwise all lines are captured.
+    #
+    # ```
+    # content=<regex>
+    # ```
+    content_pattern: re.Pattern = re.compile(r"content=[\"']?([^\"']*)[\"']?")
+    content: str = None
+    #
+    # #### Stop capture
+    #
+    # Regex expression to indicate capture should stop.
+    #
+    # ```
+    # stop=<regex>
+    # ```
+    stop_pattern: re.Pattern = re.compile(r"stop=[\"']?([^\"']*)[\"']?")
+    # /md
+
+
 class ExtractionPattern:
     """An ExtractionPattern for a file."""
     # md file="ExtractionPattern.snippet"
@@ -89,90 +137,49 @@ class ExtractionPattern:
             else:
                 self.replace.append((re.compile(item[0]), item[1]))
 
-        # md file=inline_params.snippet
-        # These parameters should be on the same line as the start block.
-        #
-        # For example:
-        #
-        # ```
-        #  /**md file="new_name.md" trim=2 content="^\s*\/\/\s?(.*)$"
-        # ```
-        #
-        # #### Set output file name
-        #
-        #  Filename is relative to the folder of the file being processed.
-        #
-        # ```
-        # file=<name>
-        # ```
-        self._filename_pattern = re.compile(r"file=[\"']?(\w+.\w+)[\"']?\b")
-        self._filename = None
-        #
-        # #### Trim the front of a line
-        #
-        # Useful for removing leading spaces.
-        #
-        # ```
-        # trim=#
-        # ```
-        self._trim_pattern = re.compile(r"trim=[\"']?(\d+)[\"']?\b")
-        self._trim = 0
-        # #### Capture content
-        #
-        # Regex expression to capture content, otherwise all lines are captured.
-        #
-        # ```
-        # content=<regex>
-        # ```
-        self._content_pattern = re.compile(r"content=[\"']?([^\"']*)[\"']?")
-        self._content = None
-        #
-        # #### Stop capture
-        #
-        # Regex expression to indicate capture should stop.
-        #
-        # ```
-        # stop=<regex>
-        # ```
-        self._stop_pattern = re.compile(r"stop=[\"']?([^\"']*)[\"']?")
-        # /md
+        self.inline = InlineParams()
 
     def setup(self, line: str) -> None:
         """Process input parameters."""
-        self._filename = None
-        file_match = get_match(self._filename_pattern, line)
+        setup_inline = InlineParams()
+
+        file_match = _get_match(setup_inline.filename_pattern, line)
         if file_match and file_match.lastindex:
-            self._filename = file_match[file_match.lastindex]
+            setup_inline.filename = file_match[file_match.lastindex]
 
-        self._trim = 0
-        trim_match = get_match(self._trim_pattern, line)
+        trim_match = _get_match(setup_inline.trim_pattern, line)
         if trim_match and trim_match.lastindex:
-            self._trim = int(trim_match[trim_match.lastindex])
+            setup_inline.trim = int(trim_match[trim_match.lastindex])
 
-        self._content = None
-        content_match = get_match(self._content_pattern, line)
+        content_match = _get_match(setup_inline.content_pattern, line)
         if content_match and content_match.lastindex:
             regex_pattern = content_match[content_match.lastindex]
-            self._content = re.compile(regex_pattern)
+            setup_inline.content = re.compile(regex_pattern)
 
+        # choose which stop option to use.
+        # Order by;
+        #     1. default from extraction pattern settings
+        #     2. default from inline params
         self.stop = self._stop_default
-        stop_match = get_match(self._stop_pattern, line)
+        stop_match = _get_match(setup_inline.stop_pattern, line)
         if stop_match and stop_match.lastindex:
             regex_pattern = stop_match[stop_match.lastindex]
             self.stop = re.compile(regex_pattern)
 
+        self.inline = setup_inline
+
     def get_filename(self) -> str:
         """Returns the filename if defined in start arguments."""
-        return self._filename
+        return self.inline.filename
 
     def replace_line(self, line: str) -> str:
         """Apply the specified replacements to the line and return it."""
         # Process trimming
-        if self._trim:
-            line = line[self._trim:]
+        if self.inline.trim:
+            line = line[self.inline.trim:]
         # Process inline content regex
-        if self._content:
-            match_object = get_match(self._content, line)
+        if self.inline.content:
+            match_object = _get_match(self.inline.content, line)
             if match_object.lastindex:
                 return match_object[match_object.lastindex]
         # Preform replace operations
@@ -214,126 +221,132 @@ class LazyFile:
         return os.path.join(self.file_directory, self.file_name)
 
     def write(self, arg: str) -> None:
-        """Create and write the file, only if not empty."""
-        if not arg:
+        """Create and write a string line to the file, iff not none."""
+        if arg is None:
             return
         if self.file_object is None:
             filename = os.path.join(self.file_directory, self.file_name)
             os.makedirs(self.file_directory, exist_ok=True)
             self.file_object = open(filename, 'w+')
-        self.file_object.write(arg)
+
+        def get_line(line: str) -> str:
+            """Returns line with EOL."""
+            return line if line.endswith("\n") else line + '\n'
+
+        self.file_object.write(get_line(arg))
 
     def close(self) -> str:
         """Finish the file."""
         if self.file_object is not None:
-            file = os.path.join(self.file_directory, self.file_name)
-            utils.log.debug("        ... extracted %s", file)
+            file_path = os.path.join(self.file_directory, self.file_name)
+            utils.log.debug("        ... extracted %s", file_path)
             self.file_object.close()
             self.file_object = None
-            return file
+            return file_path
         return None
 
 
 class StreamExtract:
-    """Extract documentation portions of files to an output stream."""
+    """Extract files to an output stream.
+
+    Optionally filter using a list of ExtractionPatterns.
+    """
 
     def __init__(
             self,
-            input_stream: LazyFile,
+            input_stream: TextIOWrapper,
             output_stream: LazyFile,
             terminate: re.Pattern = None,
             patterns: ExtractionPattern = None,
             **kwargs):
         """Initialize StreamExtract with input and output streams."""
         self.input_stream = input_stream
-        self.default_stream = output_stream
         self.output_stream = output_stream
         self.terminate = terminate
         self.patterns = patterns
-        self.wrote_something = False
-        self.output_files = []
-        self.streams = {
+
+        self._default_stream = output_stream
+        self._output_files = []
+        self._streams = {
             output_stream.file_name: output_stream
         }
 
-    def transcribe(self, text: str) -> None:
-        """Write some text and record if something was written."""
-        self.output_stream.write(text)
-        if text:
-            self.wrote_something = True
-
-    def try_extract_match(
+    def _try_extract_match(
             self,
             match_object: re.Match,
             emit_last: bool = True) -> bool:
-        """Extract match into output.
+        """Extracts line iff there's a match.
 
-        If _match_object_ is not false-y, returns true.
-        If extract flag is true, emits the last group of the match if any.
+        Returns:
+            True iff match_object exists.
         """
         if not match_object:
             return False
         if match_object.lastindex and emit_last:
-            self.transcribe(get_line(match_object[match_object.lastindex]))
+            self.output_stream.write(match_object[match_object.lastindex])
         return True
 
     def close(self) -> list:
-        """Returns true if something was written"""
+        """Close the file and return a list of filenames written to."""
         file = self.output_stream.close()
-        if file and self.wrote_something:
-            self.output_files.append(file)
-        return self.output_files
+        if file:
+            self._output_files.append(file)
+        return self._output_files
 
-    def set_output_file(self, filename: str) -> None:
-        """Set output stream from filename."""
+    def set_output_file(self, filename: str) -> LazyFile:
+        """Set the current output stream from filename and return the stream."""
         output_stream = self.output_stream
         if filename:
             # If we've opened this file before, re-use its stream.
-            if filename in self.streams:
-                return self.set_output_stream(self.streams[filename])
+            if filename in self._streams:
+                return self.set_output_stream(self._streams[filename])
             # Otherwise, make a new one and save it to the list.
             output_stream = LazyFile(
                 self.output_stream.file_directory, filename)
-            self.streams[filename] = output_stream
-        self.set_output_stream(output_stream)
+            self._streams[filename] = output_stream
+        return self.set_output_stream(output_stream)
 
-    def set_output_stream(self, stream: LazyFile) -> None:
-        """Set the output stream."""
+    def set_output_stream(self, stream: LazyFile) -> LazyFile:
+        """Set the current output stream and return the stream."""
         if self.output_stream != stream:
             self.close()
             self.output_stream = stream
+        return self.output_stream
 
     def extract(self, **kwargs) -> list:
         """Extract from file with semiliterate configuration.
 
-        Invoke this method to perform the extraction. Returns true if
-        any text is actually extracted, false otherwise.
+        Invoke this method to perform the extraction.
+
+        Returns:
+            A list of files extracted.
         """
         active_pattern = None if self.patterns else ExtractionPattern()
-        for pattern in self.patterns:
+        patterns = self.patterns if self.patterns else []
+        for pattern in patterns:
             if not pattern.start:
                 active_pattern = pattern
 
         for line in self.input_stream:
             # Check terminate, regardless of state:
-            if self.try_extract_match(
-                    get_match(self.terminate, line), active_pattern):
+            if self._try_extract_match(
+                    _get_match(self.terminate, line), active_pattern):
                 return self.close()
             # Change state if flagged to do so:
             if active_pattern is None:
-                for pattern in self.patterns:
-                    start = get_match(pattern.start, line)
+                for pattern in patterns:
+                    start = _get_match(pattern.start, line)
                     if start:
                         active_pattern = pattern
                         active_pattern.setup(line)
                         self.set_output_file(active_pattern.get_filename())
-                        self.try_extract_match(start)
+                        self._try_extract_match(start)
                         break
                 continue
             # We are extracting. See if we should stop:
-            if self.try_extract_match(get_match(active_pattern.stop, line)):
+            if self._try_extract_match(_get_match(active_pattern.stop, line)):
                 active_pattern = None
-                self.set_output_stream(self.default_stream)
+                self.set_output_stream(self._default_stream)
                 continue
             # Extract all other lines in the normal way:
             self.extract_line(line, active_pattern)
@@ -341,8 +354,8 @@ class StreamExtract:
 
     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)
+        line = extraction_pattern.replace_line(line)
+        self.output_stream.write(line)
 
 
 class Semiliterate:
@@ -397,18 +410,25 @@ class Semiliterate:
         self.file_filter = re.compile(pattern)
         self.destination = destination
         self.terminate = (terminate is not None) and re.compile(terminate)
-        self.patterns = []
+        self.extractions = []
         if not extract:
             extract = []
         if isinstance(extract, dict):
             # if there is only one extraction pattern, allow it to be a single
             # dict entry
             extract = [extract]
-        for pattern in extract:
-            self.patterns.append(ExtractionPattern(**pattern))
+        for extract_params in extract:
+            self.extractions.append(ExtractionPattern(**extract_params))
 
     def filename_match(self, name: str) -> str:
-        """Get the filename for the match, otherwise return None."""
+        """Get the filename for the match, otherwise return None.
+
+        Args:
+            name (str): The name to match with the pattern filter
+
+        Returns:
+            The output filename for 'name' or None
+        """
         name_match = self.file_filter.search(name)
         if name_match:
             new_name = os.path.splitext(name)[0] + '.md'
@@ -425,7 +445,12 @@ class Semiliterate:
             **kwargs) -> list:
         """Try to extract documentation from file with name.
 
-        Returns True if extraction was successful.
+        Args:
+            from_directory (str): The source directory
+            from_file (str): The source filename within directory
+            destination_directory (str): The destination directory
+
+        Returns a list of extracted files.
         """
         to_file = self.filename_match(from_file)
         if not to_file:
@@ -439,11 +464,11 @@ class Semiliterate:
                     input_stream=original_file,
                     output_stream=LazyFile(destination_directory, to_file),
                     terminate=self.terminate,
-                    patterns=self.patterns,
+                    patterns=self.extractions,
                     **kwargs)
                 return extraction.extract()
         except (UnicodeDecodeError) as error:
-            utils.log.info("mkdocs-simple-plugin: Skipped  %s", from_file_path)
+            utils.log.debug("mkdocs-simple-plugin: Skipped  %s", from_file_path)
             utils.log.debug(
                 "mkdocs-simple-plugin: Error details: %s", str(error))
         except (OSError, IOError) as error:

{mkdocs_simple_plugin-3.0.0 → mkdocs_simple_plugin-3.2.0}/mkdocs_simple_plugin/simple.py

@@ -1,8 +1,8 @@
 """Simple module handles document extraction from source files."""
-import os
 import fnmatch
-import stat
+import os
 import pathlib
+import stat
 
 from shutil import copy2 as copy
 from dataclasses import dataclass
@@ -26,10 +26,10 @@ class Simple():
     # pylint: disable=too-many-instance-attributes
     def __init__(
             self,
-            build_docs_dir: str,
-            include_folders: list,
-            include_extensions: list,
-            ignore_folders: list,
+            build_dir: str,
+            folders: list,
+            include: list,
+            ignore: list,
             ignore_hidden: bool,
             ignore_paths: list,
             semiliterate: list,
@@ -37,23 +37,22 @@ class Simple():
         """Initialize module instance with settings.
 
         Args:
-            build_docs_dir (str): Output directory for processed files
-            include_folders (list): Glob of folders to search for files
-            include_extensions (list): Glob of filenames to copy directly to
-                output
-            ignore_folders (list): Glob of paths to exclude
+            build_dir (str): Output directory for processed files
+            folders (list): Glob of folders to search for files
+            include (list): Glob of filenames to copy directly to output
+            ignore (list): Glob of paths to exclude
             ignore_hidden (bool): Whether to ignore hidden files for processing
             ignore_paths (list): Absolute filepaths to exclude
             semiliterate (list): Settings for processing file content in
                 Semiliterate
 
         """
-        self.build_dir = build_docs_dir
-        self.include_folders = set(include_folders)
-        self.copy_glob = set(include_extensions)
-        self.ignore_glob = set(ignore_folders)
-        self.ignore_hidden = ignore_hidden
-        self.hidden_prefix = set([".", "__"])
+        self.build_dir = build_dir
+        self.folders = set(folders)
+        self.doc_glob = set(include)
+        self.ignore_glob = set(ignore)
+        self.ignore_hidden = ignore_hidden  # to be deprecated
+        self.hidden_prefix = set([".", "__"])  # to be deprecated
         self.ignore_paths = set(ignore_paths)
         self.semiliterate = []
         for item in semiliterate:
@@ -64,7 +63,7 @@ class Simple():
         files = []
         # Get all of the entries that match the include pattern.
         entries = []
-        for pattern in self.include_folders:
+        for pattern in self.folders:
             entries.extend(pathlib.Path().glob(pattern))
         # Ignore any entries that match the ignore pattern
         entries[:] = [
@@ -101,7 +100,7 @@ class Simple():
         mkdocsignore = os.path.join(base_path, ".mkdocsignore")
         if os.path.exists(mkdocsignore):
             ignore_list = []
-            with open(mkdocsignore, "r") as txt_file:
+            with open(mkdocsignore, mode="r", encoding="utf-8") as txt_file:
                 ignore_list = txt_file.read().splitlines()
                 # Remove all comment lines
                 ignore_list = [x for x in ignore_list if not x.startswith('#')]
@@ -115,12 +114,12 @@ class Simple():
             return True
         return False
 
-    def should_copy_file(self, name: str) -> bool:
-        """Check if file should be copied."""
+    def is_doc_file(self, name: str) -> bool:
+        """Check if file is a desired doc file."""
         def match_pattern(name, pattern):
             return fnmatch.fnmatch(name, pattern) or pattern in name
 
-        return any(match_pattern(name, pattern) for pattern in self.copy_glob)
+        return any(match_pattern(name, pattern) for pattern in self.doc_glob)
 
     def should_extract_file(self, name: str):
         """Check if file should be extracted."""
@@ -142,13 +141,18 @@ class Simple():
                 return any(name.startswith(pattern)
                            for pattern in self.hidden_prefix)
             return any(hidden_prefix(part) for part in parts)
-
-        extract = True
+        # Check if file is text based
+        try:
+            with open(name, 'r', encoding='utf-8') as f:
+                _ = f.read()
+        except UnicodeDecodeError:
+            return False
+
+        # Check if file is hidden and should ignore
         if self.ignore_hidden:
             is_hidden = has_hidden_prefix(name) or has_hidden_attribute(name)
-            extract = not is_hidden
-
-        return extract
+            return not is_hidden
+        return True
 
     def merge_docs(self, from_dir, dirty=False):
         """Merge docs directory"""
@@ -173,7 +177,11 @@ class Simple():
                     source_file, destination_file)
         self.ignore_paths.add(from_dir)
 
-    def build_docs(self, dirty=False, last_build_time=None) -> list:
+    def build_docs(
+            self,
+            dirty=False,
+            last_build_time=None,
+            do_copy=False) -> list:
         """Build the docs directory from workspace files."""
         paths = []
         files = self.get_files()
@@ -188,8 +196,9 @@ class Simple():
             build_prefix = os.path.normpath(
                 os.path.join(self.build_dir, from_dir))
 
-            copy_paths = self.try_copy_file(from_dir, name, build_prefix)
-            if copy_paths:
+            doc_paths = self.get_doc_file(
+                from_dir, name, build_prefix, do_copy)
+            if doc_paths:
                 paths.append(
                     SimplePath(
                         output_root=".",
@@ -231,17 +240,23 @@ class Simple():
 
         return []
 
-    def try_copy_file(self, from_dir: str, name: str, to_dir: str) -> list:
+    def get_doc_file(
+            self,
+            from_dir: str,
+            name: str,
+            to_dir: str,
+            do_copy: bool) -> list:
         """Copy file with the same name to a new directory.
 
         Returns true if file copied.
         """
         original = os.path.join(from_dir, name)
-        destination = os.path.join(to_dir, name)
 
-        if not self.should_copy_file(os.path.join(from_dir, name)):
+        if not self.is_doc_file(os.path.join(from_dir, name)):
             return []
 
-        os.makedirs(to_dir, exist_ok=True)
-        copy(original, destination)
+        if do_copy:
+            destination = os.path.join(to_dir, name)
+            os.makedirs(to_dir, exist_ok=True)
+            copy(original, destination)
         return [original]

{mkdocs_simple_plugin-3.0.0 → mkdocs_simple_plugin-3.2.0}/pyproject.toml

@@ -23,19 +23,18 @@ classifiers = [
     "Intended Audience :: Information Technology",
     "Programming Language :: Python",
     "Programming Language :: Python :: 3 :: Only",
-    "Programming Language :: Python :: 3.7",
     "Programming Language :: Python :: 3.8",
     "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11"
 ]
 # md file="versions.snippet"
-# _Python 3.x, 3.7, 3.8, 3.9, 3.10, 3.11 supported._
+# _Python 3.x, 3.8, 3.9, 3.10, 3.11 supported._
 # /md
 dependencies = [
     "click>=7.1",
     "MarkupSafe>=2.1.1",
-    "mkdocs>=1.4.0",
+    "mkdocs>=1.6.0",
     "PyYAML>=6.0",
 ]
 

mkdocs_simple_plugin-3.0.0/mkdocs_simple_plugin/README.md

@@ -1,42 +0,0 @@
-# Package Guide
-
-## Prerequisites
-
-{% include "setup.snippet" %}
-
-
-## Building
-
-{% include "build.snippet" %}
-
-## Testing
- 
-{% include "tests/linters.snippet" %}
-
-{% include "tests/unit_tests.snippet" %}
-
-{% include "tests/integration_tests.snippet" %}
-
-{% include "tests/local_tests.snippet" %}
-
-## VSCode
-
-Included in this package is a VSCode workspace and development container.  See [how I develop with VSCode and Docker](https://allisonthackston.com/articles/docker-development.html) and [how I use VSCode tasks](https://allisonthackston.com/articles/vscode-tasks.html).
-
-## Packaging
-
-[![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch)
-
-The project uses Hatch to build and package the plugin
-
-### Build the package
-
-```bash
-hatch build
-```
-
-### Publish the package
-
-```bash
-hatch publish
-```