Rename config options to simplify (#569)

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

@@ -9,7 +9,7 @@
 site_name: ok-mkdocs-docs-extensions
 plugins:
   - simple:
-      include_extensions: [".txt"]
+      include: [".txt"]
 ```
 ## Input
 

examples/ok-mkdocs-docs-extensions/mkdocs-test.yml

@@ -2,4 +2,4 @@
 site_name: ok-mkdocs-docs-extensions
 plugins:
   - simple:
-      include_extensions: [".txt"]
+      include: [".txt"]

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

@@ -9,7 +9,7 @@
 site_name: ok-mkdocs-docs-ignore
 plugins:
   - simple:
-      ignore_folders: ["subfolder"]
+      ignore: ["subfolder"]
 ```
 ## Input
 

examples/ok-mkdocs-docs-ignore/mkdocs-test.yml

@@ -2,4 +2,4 @@
 site_name: ok-mkdocs-docs-ignore
 plugins:
   - simple:
-      ignore_folders: ["subfolder"]
+      ignore: ["subfolder"]

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

@@ -9,7 +9,7 @@
 site_name: ok-mkdocs-docs-include
 plugins:
   - simple:
-      include_folders: ["subfolder/**"]
+      folders: ["subfolder/**"]
 ```
 ## Input
 

examples/ok-mkdocs-docs-include/mkdocs-test.yml

@@ -2,4 +2,4 @@
 site_name: ok-mkdocs-docs-include
 plugins:
   - simple:
-      include_folders: ["subfolder/**"]
+      folders: ["subfolder/**"]

examples/ok-with-macros/README.md

@@ -13,7 +13,7 @@ docs_dir: /tmp/mkdocs-simple/ok-with-macros/docs
 plugins:
     - search
     - simple:
-          include_extensions:
+          include:
               - ".yml"
     - macros:
           verbose: True
@@ -88,7 +88,7 @@ docs_dir: /tmp/mkdocs-simple/ok-with-macros/docs
 plugins:
   - search
   - simple:
-      include_extensions:
+      include:
         - .yml
   - macros:
       verbose: true
@@ -110,7 +110,7 @@ docs_dir: /tmp/mkdocs-simple/ok-with-macros/docs
 plugins:
   - search
   - simple:
-      include_extensions:
+      include:
         - .yml
   - macros:
       verbose: true

examples/ok-with-macros/example.grepout

@@ -6,7 +6,7 @@ docs_dir: /tmp/mkdocs-simple/ok-with-macros/docs
 plugins:
   - search
   - simple:
-      include_extensions:
+      include:
         - .yml
   - macros:
       verbose: true

examples/ok-with-macros/mkdocs-test.yml

@@ -6,7 +6,7 @@ docs_dir: /tmp/mkdocs-simple/ok-with-macros/docs
 plugins:
     - search
     - simple:
-          include_extensions:
+          include:
               - ".yml"
     - macros:
           verbose: True

examples/ok-with-macros/module.grepout

@@ -8,7 +8,7 @@ docs_dir: /tmp/mkdocs-simple/ok-with-macros/docs
 plugins:
   - search
   - simple:
-      include_extensions:
+      include:
         - .yml
   - macros:
       verbose: true

mkdocs_simple_plugin/README.md

@@ -4,7 +4,6 @@
 
 {% include "setup.snippet" %}
 
-
 ## Building
 
 {% include "build.snippet" %}
@@ -21,13 +20,25 @@
 
 ## 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).
+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
 
-[![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 [![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
+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
 
@@ -40,3 +51,5 @@ hatch build
 ```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/plugin.py

@@ -107,22 +107,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 (renamed)
+        #
+        # Renamed [ignore](#ignore)
+        ('ignore_folders', config_options.Deprecated(
+            moved_to="ignore", removed=False)),
         #
-        # ### ignore_folders
+        # ### 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=True)),
         #
         # ### merge_docs_dir
         #
@@ -132,17 +158,28 @@ 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='')),
+        #
+        # ### include_extensions (renamed)
         #
-        # ### include_extensions
+        # 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,7 +297,7 @@ def __init__(self):
         # 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
@@ -285,31 +322,31 @@ 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'] 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']))
@@ -352,8 +389,8 @@ def on_serve(self, server, *, config, builder):
         """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/simple.py

@@ -1,7 +1,6 @@
 """Simple module handles document extraction from source files."""
-import os
 import fnmatch
-import stat
+import os
 import pathlib
 
 from shutil import copy2 as copy
@@ -26,34 +25,29 @@ class Simple():
     # pylint: disable=too-many-instance-attributes
     def __init__(
             self,
-            build_docs_dir: str,
-            include_folders: list,
-            include_extensions: list,
-            ignore_folders: list,
-            ignore_hidden: bool,
+            build_dir: str,
+            folders: list,
+            include: list,
+            ignore: list,
             ignore_paths: list,
             semiliterate: list,
             **kwargs):
         """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
-            ignore_hidden (bool): Whether to ignore hidden files for processing
+            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_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.copy_glob = set(include)
+        self.ignore_glob = set(ignore)
         self.ignore_paths = set(ignore_paths)
         self.semiliterate = []
         for item in semiliterate:
@@ -64,7 +58,7 @@ def get_files(self) -> list:
         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[:] = [
@@ -124,31 +118,13 @@ def match_pattern(name, pattern):
 
     def should_extract_file(self, name: str):
         """Check if file should be extracted."""
-        def has_hidden_attribute(filepath):
-            """Returns true if hidden attribute is set."""
-            try:
-                return bool(os.stat(filepath).st_file_attributes &
-                            stat.FILE_ATTRIBUTE_HIDDEN)
-            except (AttributeError, AssertionError):
-                return False
-
-        def has_hidden_prefix(filepath):
-            """Returns true if the file starts with a hidden prefix."""
-            parts = filepath.split(os.path.sep)
-
-            def hidden_prefix(name):
-                if name == ".":
-                    return False
-                return any(name.startswith(pattern)
-                           for pattern in self.hidden_prefix)
-            return any(hidden_prefix(part) for part in parts)
-
-        extract = True
-        if self.ignore_hidden:
-            is_hidden = has_hidden_prefix(name) or has_hidden_attribute(name)
-            extract = not is_hidden
-
-        return extract
+        # Check if file is text based
+        try:
+            with open(name, 'r', encoding='utf-8') as f:
+                _ = f.read()
+                return True
+        except UnicodeDecodeError:
+            return False
 
     def merge_docs(self, from_dir, dirty=False):
         """Merge docs directory"""