mkdocs-partial 1.2.1__py3-none-any.whl

mkdocs_partial/integrations/spellcheck_plugin_shim.py

@@ -0,0 +1,46 @@
+# pylint: disable=unused-argument
+import os
+import re
+from typing import Any
+
+from mkdocs import plugins
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.structure.files import Files
+from mkdocs.structure.pages import Page
+from mkdocs_spellcheck.plugin import SpellCheckPlugin  # pylint: disable=import-error
+
+import mkdocs_partial
+
+
+class SpellCheckShim(SpellCheckPlugin):
+    SKIP_SPELLCHECK = re.compile("<!-- *spellcheck: +disable *-->.*?($|<!-- *spellcheck: +enable *-->)", re.DOTALL)
+
+    def on_page_content(self, html: str, page: Page, **kwargs: Any) -> None:
+        if not mkdocs_partial.SpellCheckShimActive:
+            super().on_page_content(html, page, **kwargs)
+            return
+
+        if page.meta.get("spellcheck", True):
+            html_to_spellcheck = self.SKIP_SPELLCHECK.sub("", html)
+            if page.file.generated_by is None:
+                super().on_page_content(html_to_spellcheck, page, **kwargs)
+            else:
+                original_path = page.file.src_path
+                try:
+                    page.file.src_path = f"{page.file.generated_by}:{page.file.src_path}"
+                    super().on_page_content(html_to_spellcheck, page, **kwargs)
+                finally:
+                    page.file.src_path = original_path
+
+    @plugins.event_priority(-100)
+    def on_files(self, files: Files, /, *, config: MkDocsConfig) -> Files | None:
+        if not mkdocs_partial.SpellCheckShimActive:
+            return files if not hasattr(super(), "on_files") else super().on_files(files, config=config)
+
+        known_words_files = list(file for file in files if os.path.basename(file.src_path) == "known_words.txt")
+        # remove known_words.txt files to avoid exposing them wth other docs
+        for file in known_words_files:
+            self.known_words.update(file.content_string.splitlines())
+            files.remove(file)
+
+        return files

mkdocs_partial/mkdcos_helpers.py

@@ -0,0 +1,97 @@
+import glob
+import os
+from importlib.metadata import EntryPoint
+from pathlib import Path
+
+import watchdog
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.livereload import LiveReloadServer
+from mkdocs.plugins import BasePlugin
+from watchdog.events import FileSystemEvent
+
+
+def normalize_path(path: str) -> str:
+    return os.path.normpath(path).replace("\\", "/")
+
+
+def get_mkdocs_plugin(name: str, entrypoint: str, config: MkDocsConfig) -> BasePlugin | None:
+    plugin_entrypoint: EntryPoint = MkDocsConfig.plugins.installed_plugins.get(name, None)
+    plugin = config.plugins.get(name, None)
+    if (
+        # macros entry point is registered by mkdocs_macros plugin
+        plugin_entrypoint is not None
+        and plugin_entrypoint.value == entrypoint
+        # macros_plugin plugin is active
+        and plugin is not None
+    ):
+        return plugin
+    return None
+
+
+def get_mkdocs_plugin_name(plugin: BasePlugin, config: MkDocsConfig):
+    for name, instance in config.plugins.items():
+        if instance == plugin:
+            return name
+    return None
+
+
+def replace_mkdocs_plugin_entrypoint(name, entrypoint, new_entrypoint):
+    found_entrypoint: EntryPoint = MkDocsConfig.plugins.installed_plugins.get(name, None)
+    if found_entrypoint is not None and found_entrypoint.value == entrypoint:
+        MkDocsConfig.plugins.installed_plugins[name] = EntryPoint(name, new_entrypoint, "mkdocs.plugins")
+        if hasattr(MkDocsConfig.plugins, "plugins"):
+            plugin = MkDocsConfig.plugins.plugins.get(name, None)
+            assert plugin is None
+        return True
+    return False
+
+
+def mkdocs_watch_ignore_path(server: LiveReloadServer, config: MkDocsConfig, ignore_dir, watched_dir=None):
+    if watched_dir is None:
+        watched_dir = config.docs_dir
+
+    try:
+        # Unwatch the directory watched by mkdocs.
+        server.unwatch(watched_dir)
+    except KeyError:
+        # watched_dir is not watched
+        pass
+
+    def callback(event: FileSystemEvent):
+        # Ignore events for directories as they do not affect mkdocs livereload
+        if event.is_directory:
+            return
+
+        # Ignore events for files within `ignore_dir`
+        if Path(event.src_path).is_relative_to(ignore_dir):
+            return
+
+        # Unwatch deleted files
+        if event.event_type in [watchdog.events.EVENT_TYPE_DELETED, watchdog.events.EVENT_TYPE_MOVED]:
+            try:
+                server.unwatch(event.src_path)
+            except KeyError:
+                # src_path is not watched
+                pass
+
+        # Watch created files
+        if event.event_type in [watchdog.events.EVENT_TYPE_CREATED]:
+            server.watch(event.src_path)
+        if event.event_type in [watchdog.events.EVENT_TYPE_MOVED]:
+            server.watch(event.dest_path)
+
+        # Touch mkdocs config file which is always watched to trigger rebuild and handle created/deleted files
+        os.utime(config.config_file_path)
+        return
+
+    # Call mkdocs watch for files within in `watched_dir` tree except those in `ignore_dir`
+    for path in glob.glob(os.path.join(watched_dir, "**/*"), recursive=True):
+        if os.path.isfile(path) and not Path(path).is_relative_to(ignore_dir):
+            server.watch(path)
+
+    # Start watching `watched_dir` updating mkdocs watches for files that are not in `ignored_dir`
+    handler = watchdog.events.FileSystemEventHandler()
+    handler.on_moved = callback
+    handler.on_deleted = callback
+    handler.on_created = callback
+    server.observer.schedule(handler, watched_dir, recursive=True)

mkdocs_partial/packages/packager.py

@@ -0,0 +1,218 @@
+import glob
+import hashlib
+import importlib
+import logging
+import os
+import zipfile
+from abc import ABC
+from datetime import datetime
+from importlib.metadata import entry_points
+from itertools import chain
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from typing import List
+
+from packaging.requirements import Requirement
+
+from mkdocs_partial import MODULE_NAME_RESTRICTED_CHARS, version
+from mkdocs_partial.docs_package_plugin import DocsPackagePlugin
+from mkdocs_partial.mkdcos_helpers import normalize_path
+from mkdocs_partial.templating.markdown_extension import TemplaterMarkdownExtension
+from mkdocs_partial.templating.templater import Templater
+
+
+class Packager(ABC):
+    def __init__(self, templates_dir):
+        self.__templates_dir = templates_dir
+
+    def pack(  # pylint: disable=too-many-positional-arguments
+        self,
+        package_name,
+        package_version,
+        package_description,
+        output_dir,
+        resources_src_dir,
+        excludes=None,
+        resources_package_dir=None,
+        add_self_dependency=True,
+        requirements_path=None,
+        freeze=False,
+        **kwargs,
+    ):
+        resources_src_dir = os.path.abspath(resources_src_dir)
+        resources_src_dir = normalize_path(resources_src_dir)
+
+        output_dir = normalize_path(output_dir)
+        if excludes is None:
+            excludes = []
+        start = datetime.now()
+        logging.info(f"Building package {package_name} v{package_version} form folder {resources_src_dir}.")
+        module_name = MODULE_NAME_RESTRICTED_CHARS.sub("_", package_name.lower())
+
+        wheel_filename = os.path.join(output_dir, f"{module_name}-{package_version}-py3-none-any.whl")
+        script_dir = os.path.dirname(os.path.realpath(__file__))
+        templates_dir = os.path.join(script_dir, os.path.join("templates", self.__templates_dir))
+        templater = Templater(templates_dir=templates_dir).extend(TemplaterMarkdownExtension())
+
+        requirements = []
+        if requirements_path is not None:
+            if not os.path.isfile(requirements_path) and not os.path.isabs(requirements_path):
+                requirements_path = os.path.join(resources_src_dir, requirements_path)
+            if os.path.isfile(requirements_path):
+                requirements = self.parse_requirements(requirements_path)
+
+        if add_self_dependency:
+            self_dependency = Requirement(f"mkdocs-partial >={version.__version__}")
+            requirements.append(self_dependency)
+
+        if freeze:
+            requirements = Packager.freeze_requirements(requirements)
+        args = {**kwargs}
+        args.update(
+            {
+                "package_name": package_name,
+                "module_name": module_name,
+                "package_version": package_version,
+                "requirements": list(requirements),
+                "package_description": package_description,
+            }
+        )
+
+        with zipfile.ZipFile(wheel_filename, "w") as zipf:
+            dist_info_dir = f"{module_name}-{package_version}.dist-info"
+
+            record_lines = []
+
+            for templates_subdir, wheel_subdir, record in [
+                ("dist-info", dist_info_dir, False),
+                ("package", module_name, True),
+            ]:
+                for file in glob.glob(os.path.join(templates_dir, templates_subdir, "**/*"), recursive=True):
+                    if os.path.isfile(file):
+                        path = os.path.relpath(os.path.normpath(file), os.path.join(templates_dir, templates_subdir))
+                        path = os.path.join(wheel_subdir, path).replace("\\", "/")
+                        path = templater.template_string(path, **args)
+                        if path.lower().endswith(".j2"):
+                            path = path[:-3]
+                        content = templater.template(os.path.relpath(file, templates_dir).replace("\\", "/"), **args)
+                        content.replace("\r\n", "\n")
+                        file_data = bytes(content, "utf8")
+                        record_line = self.write_file(path, file_data, zipf)
+                        if record:
+                            record_lines.append(record_line)
+
+            excluded = chain(
+                *[
+                    glob.glob(normalize_path(os.path.join(resources_src_dir, exclude)), recursive=True)
+                    for exclude in excludes
+                ]
+            )
+            excluded = [normalize_path(exclude) for exclude in excluded]
+            for exclude in excludes:
+                logging.info(f"Excluded glob {normalize_path(os.path.join(resources_src_dir, exclude))}")
+            for exclude in excluded:
+                logging.info(f"Excluding file {exclude}")
+            for file in glob.glob(os.path.join(resources_src_dir, "**/*"), recursive=True):
+                file = normalize_path(file)
+                if os.path.isfile(file) and file not in excluded:
+                    logging.info(f"Packaging file {file}")
+                    path = module_name
+                    if resources_package_dir is not None and resources_package_dir != "":
+                        path = os.path.join(path, resources_package_dir)
+                    path = os.path.join(path, os.path.relpath(file, resources_src_dir))
+                    path = normalize_path(path)
+                    record_lines.append(self.write_file(path, Path(file).read_bytes(), zipf))
+
+            zipf.writestr(f"{dist_info_dir}/RECORD", "\n".join(record_lines) + "\n")
+
+        logging.info(f"Package is built within {(datetime.now() - start)}. File is written to {wheel_filename}")
+
+    @staticmethod
+    def write_file(arcname, file_data, zipf):
+        sha256_hash = hashlib.sha256(file_data).hexdigest()
+        file_size = len(file_data)
+        with NamedTemporaryFile("wb", delete_on_close=False) as file:
+            file.write(file_data)
+            file.close()
+            zipf.write(file.name, arcname)
+        return f"{arcname},sha256={sha256_hash},{file_size}"
+
+    @staticmethod
+    def parse_requirements(path):
+        with open(path) as f_requirements:
+            requirements = [
+                Requirement(dependency)
+                for dependency in f_requirements.readlines()
+                if not dependency.isspace() and dependency != "" and dependency[0] != "#"
+            ]
+        return requirements
+
+    @staticmethod
+    def freeze(path):
+        requirements = Packager.parse_requirements(path)
+
+        with open(path, "w") as f_requirements:
+            for requirement in Packager.freeze_requirements(requirements):
+                f_requirements.write(f"{requirement}\n")
+        return True, None
+
+    @staticmethod
+    def freeze_requirements(requirements: List[Requirement]):
+        plugin_requirements = {}
+        for mkdocs_plugin in entry_points(group="mkdocs.plugins"):
+            try:
+                plugin_class = mkdocs_plugin.load()
+            except ModuleNotFoundError:
+                continue
+
+            if issubclass(plugin_class, DocsPackagePlugin) and plugin_class != DocsPackagePlugin:
+                plugin_requirements[mkdocs_plugin.dist.name] = Requirement(
+                    f"{mkdocs_plugin.dist.name}=={mkdocs_plugin.dist.version}"
+                )
+
+        for requirement in requirements:
+            yield plugin_requirements.get(requirement.name, requirement)
+
+    @staticmethod
+    def get_mudules_from_packages(*packages: str):
+        installed_packages = list(chain(*[importlib.metadata.distributions(name=package) for package in packages]))
+        module_names = set()
+        for package in installed_packages:
+            distribution = importlib.metadata.distribution(package.metadata["Name"])
+            for file in distribution.files:
+                if (
+                    not file.name.endswith(".pyc")  # pylint: disable=too-many-boolean-expressions
+                    and "__pycache__" not in Path(file.name).parts
+                    and ".dist-info" not in Path(file.name).parts
+                    and not file.parts[0].endswith(".dist-info")
+                    and not file.parts[0].endswith(".egg-info")
+                    and ".." not in file.parts
+                ):
+                    module_name = file.parts[0]
+                    name, extension = os.path.splitext(module_name)
+                    if extension == ".py":
+                        module_name = name
+                        extension = ""
+                    if extension == "" and not name.startswith("_"):
+                        module_names.add(module_name)
+
+        return module_names
+
+
+if __name__ == "__main__":
+    modules = Packager.get_mudules_from_packages(
+        "mkdocs-material",
+        "mkdocs-glightbox",
+        "mkdocs-macros-plugin",
+        "mkdocs-spellcheck",
+        "documentation-mkdocs-landscape",
+        "documentation-mkdocs-plugins",
+        "docs-documentation-inceptum",
+        "docs-documentation",
+        "docs-cicd",
+        "docs-observability",
+        "docs-organisation",
+        "docs-infrastructure",
+        "mkdocs_partial",
+    )
+    print(modules)

mkdocs_partial/packages/templates/docs-package/dist-info/METADATA.j2

@@ -0,0 +1,7 @@
+Metadata-Version: 2.1
+Name: {{package_name}}
+Version: {{package_version}}
+Description: {{package_description}}
+{% for requirement in requirements %}
+Requires-Dist: {{requirement}}
+{% endfor %}

mkdocs_partial/packages/templates/docs-package/dist-info/WHEEL.j2

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: setuptools
+Root-Is-Purelib: true
+Tag: py3-none-any

mkdocs_partial/packages/templates/docs-package/dist-info/entry_points.txt.j2

@@ -0,0 +1,2 @@
+[mkdocs.plugins]
+{{package_name}} = {{module_name}}.plugin:Plugin

mkdocs_partial/packages/templates/docs-package/package/__init__.py.j2

@@ -0,0 +1,3 @@
+"""Initialization of {{package_name}} package."""
+
+__version__ = "{{package_version}}"

mkdocs_partial/packages/templates/docs-package/package/__pyinstaller/__init__.py.j2

@@ -0,0 +1,5 @@
+
+import os
+
+def get_hook_dirs():
+    return [os.path.dirname(__file__)]

mkdocs_partial/packages/templates/docs-package/package/__pyinstaller/hook-{{module_name}}.py.j2

@@ -0,0 +1,31 @@
+import importlib.metadata
+from PyInstaller.utils.hooks import collect_all, copy_metadata
+from mkdocs_partial.packages.packager import Packager
+from itertools import chain
+
+not_hooked_packages=["mkdocs"]
+required_distributions= not_hooked_packages+ [
+    "{{package_name}}",
+{% for requirement in requirements %}
+    "{{requirement.name}}",
+{% endfor %}
+    ]
+required_modules = Packager.get_mudules_from_packages(*required_distributions)
+
+datas=[]
+binaries=[]
+hiddenimports=[]
+
+for module in required_modules:
+    module_datas, module_binaries, module_hiddenimports = collect_all(module)
+    datas+=module_datas
+    binaries+=module_binaries
+    hiddenimports+=module_hiddenimports
+
+installed_dists = list(importlib.metadata.distributions())
+for distribution in required_distributions:
+    if any(dist for dist in  installed_dists if dist.name=="organisation-registry" ):
+        datas+=copy_metadata(distribution, recursive=True)
+
+
+

mkdocs_partial/packages/templates/docs-package/package/plugin.py.j2

@@ -0,0 +1,5 @@
+from mkdocs_partial.docs_package_plugin import DocsPackagePlugin
+
+class Plugin(DocsPackagePlugin):
+    def __init__(self, directory={{directory}}, edit_url_template={{edit_url_template}}, title={{title}}, blog_categories={{blog_categories}}):
+        super().__init__(directory=directory, edit_url_template=edit_url_template, title=title, blog_categories={{blog_categories}})

mkdocs_partial/packages/templates/site-package/dist-info/METADATA.j2

@@ -0,0 +1,7 @@
+Metadata-Version: 2.1
+Name: {{package_name}}
+Version: {{package_version}}
+Description: {{package_description}}
+{% for requirement in requirements %}
+Requires-Dist: {{requirement}}
+{% endfor %}

mkdocs_partial/packages/templates/site-package/dist-info/WHEEL.j2

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: setuptools
+Root-Is-Purelib: true
+Tag: py3-none-any

mkdocs_partial/packages/templates/site-package/dist-info/entry_points.txt.j2

@@ -0,0 +1,5 @@
+[console_scripts]
+{{package_name}} = {{module_name}}.entry_point:run
+
+[pyinstaller40]
+hook-dirs = {{module_name}}.__pyinstaller:get_hook_dirs

mkdocs_partial/packages/templates/site-package/package/__init__.py.j2

@@ -0,0 +1,3 @@
+"""Initialization of {{package_name}} package."""
+
+__version__ = "{{package_version}}"

mkdocs_partial/packages/templates/site-package/package/__main__.py.j2

@@ -0,0 +1,4 @@
+from {{module_name}} import entry_point
+
+if __name__ == '__main__':
+    entry_point.run()

mkdocs_partial/packages/templates/site-package/package/__pyinstaller/__init__.py.j2

@@ -0,0 +1,5 @@
+
+import os
+
+def get_hook_dirs():
+    return [os.path.dirname(__file__)]

mkdocs_partial/packages/templates/site-package/package/__pyinstaller/hook-{{module_name}}.py.j2

@@ -0,0 +1,30 @@
+import importlib.metadata
+from PyInstaller.utils.hooks import collect_all, copy_metadata
+from mkdocs_partial.packages.packager import Packager
+from itertools import chain
+
+not_hooked_packages=["mkdocs","pymdown-extensions","organisation-registry","symspellpy"]
+required_distributions= not_hooked_packages+ [
+    "{{package_name}}",
+{% for requirement in requirements %}
+    "{{requirement.name}}",
+{% endfor %}
+    ]
+required_modules = Packager.get_mudules_from_packages(*required_distributions)
+
+datas=[]
+binaries=[]
+hiddenimports=[]
+
+
+for module in required_modules:
+    module_datas, module_binaries, module_hiddenimports = collect_all(module)
+    datas+=module_datas
+    binaries+=module_binaries
+    hiddenimports+=module_hiddenimports
+
+installed_dists = list(importlib.metadata.distributions())
+for distribution in required_distributions:
+    if any(dist for dist in  installed_dists if dist.name=="organisation-registry" ):
+        datas+=copy_metadata(distribution, recursive=True)
+

mkdocs_partial/packages/templates/site-package/package/entry_point.py.j2

@@ -0,0 +1,11 @@
+import inspect
+import os
+
+import {{module_name}}
+from {{module_name}} import __version__
+from mkdocs_partial.site_entry_point import SiteEntryPoint
+
+def run():
+    print({{module_name}})
+    script_dir = os.path.dirname(__file__)
+    SiteEntryPoint(__version__, os.path.join(script_dir, "site"),"{{package_name}}").run()

mkdocs_partial/partial_docs_plugin.py

@@ -0,0 +1,92 @@
+# pylint: disable=unused-argument
+import traceback
+from typing import Callable, Dict, List, cast
+
+from mkdocs import plugins
+from mkdocs.config import Config, config_options
+from mkdocs.config.config_options import Plugins
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.exceptions import PluginError
+from mkdocs.plugins import BasePlugin, get_plugin_logger
+from mkdocs.structure.nav import Navigation
+from mkdocs.structure.pages import Page
+from mkdocs.utils.templates import TemplateContext
+
+from mkdocs_partial.docs_package_plugin import DocsPackagePlugin, DocsPackagePluginConfig
+
+log = get_plugin_logger("partial_docs")
+
+
+class PartialDocsPluginConfig(Config):
+    enabled = config_options.Type(bool, default=True)
+    packages = config_options.DictOfItems(config_options.SubConfig(DocsPackagePluginConfig), default={})
+
+
+class PartialDocsPlugin(BasePlugin[PartialDocsPluginConfig]):
+    docs_path_overrides: Dict[str, str] = {}
+
+    def __init__(self):
+        self.is_serve = False
+        self.is_dirty = False
+
+    def on_startup(self, *, command, dirty):
+        if not self.config.enabled:
+            return
+        self.is_serve = command == "serve"
+        self.is_dirty = dirty
+
+    def on_shutdown(self) -> None:
+        pass
+
+    def on_page_context(
+        self, context: TemplateContext, /, *, page: Page, config: MkDocsConfig, nav: Navigation
+    ) -> TemplateContext | None:
+        return context
+
+    @plugins.event_priority(100)
+    def on_config(self, config):
+        if not self.config.enabled:
+            return
+
+        global_plugins: Plugins = cast(Plugins, dict(config._schema)["plugins"])
+        assert isinstance(global_plugins, Plugins)
+
+        self.docs_package_plugins: dict[str, BasePlugin] = {}
+        try:
+            for name, plugin in self._load(global_plugins):
+                if plugin.config.enabled:
+                    src = ""
+                    if plugin.config.docs_path is not None:
+                        src = f" from source path '{plugin.config.docs_path}'"
+                    log.info(f"Injecting doc package {name} to '{plugin.directory}' directory{src}.")
+                    self.docs_package_plugins[name] = plugin
+        except Exception:
+            raise PluginError(traceback.format_exc())  # pylint: disable=raise-missing-from
+
+        # Invoke `on_startup`
+        command = "serve" if self.is_serve else "build"
+        for method in global_plugins.plugins.events["startup"]:
+            plugin = self._get_plugin(method)
+
+            if plugin and plugin in self.docs_package_plugins.values():
+                method(command=command, dirty=self.is_dirty)
+
+    # Load doc package plugins
+    def _load(self, option: Plugins) -> List[tuple[str, DocsPackagePlugin]]:
+        for entrypoint in option.installed_plugins.values():
+            try:
+                plugin_class = entrypoint.load()
+            except ModuleNotFoundError:
+                continue
+            if issubclass(plugin_class, DocsPackagePlugin) and plugin_class != DocsPackagePlugin:
+                plugin_config: DocsPackagePluginConfig = self.config.packages.setdefault(
+                    entrypoint.name, DocsPackagePluginConfig()
+                )
+                if entrypoint.name in PartialDocsPlugin.docs_path_overrides:
+                    plugin_config.docs_path = PartialDocsPlugin.docs_path_overrides[entrypoint.name]
+
+                name, plugin = option.load_plugin_with_namespace(entrypoint.name, plugin_config.data)
+                yield name, cast(DocsPackagePlugin, plugin)
+
+    def _get_plugin(self, method: Callable):
+        return getattr(method, "__self__", None)