mkdocs-partial 1.2.1__py3-none-any.whl

mkdocs_partial/site_entry_point.py

@@ -0,0 +1,151 @@
+# pylint: disable=duplicate-code
+import glob
+import inspect
+import logging
+import os
+import shutil
+import sys
+from abc import ABC
+from argparse import ArgumentParser, ArgumentTypeError
+from pathlib import Path
+
+import yaml
+from mkdocs.__main__ import build_command as mkdocs_build_command, serve_command as mkdocs_serve_command
+
+from mkdocs_partial.argparse_types import directory
+from mkdocs_partial.entry_point import add_command_parser
+from mkdocs_partial.mkdcos_helpers import normalize_path
+from mkdocs_partial.partial_docs_plugin import PartialDocsPlugin
+
+
+def local_docs(value: str):
+    values = value.split("=", maxsplit=1)
+    plugin = values[0]
+    path = "/docs" if len(values) <= 1 else values[1]
+    if not os.path.isdir(path):
+        raise ArgumentTypeError(f"directory '{path}' for plugin '{plugin}' does not exist")
+    return plugin, normalize_path(path)
+
+
+class SiteEntryPoint(ABC):
+
+    def __init__(self, version, site_root=None, prog=None):
+        self.__prog = prog
+        self.__version = version
+        if site_root is None:
+            script_dir = os.path.dirname(os.path.realpath(inspect.getfile(self.__class__)))
+            self.__default_site_root = os.path.join(script_dir, "site")
+        else:
+            self.__default_site_root = site_root
+        logging.basicConfig(
+            level=logging.INFO,
+            format="{asctime} [{levelname}] {message}",
+            style="{",
+        )
+        self.logger = logging.getLogger(__name__)
+
+    def run(self):
+
+        parser = ArgumentParser(description=f"v{self.__version}", prog=self.__prog)
+        subparsers = parser.add_subparsers(help="commands")
+        self.add_mkdocs_command_parser(
+            subparsers,
+            "serve",
+            "execute mkdocs serve",
+            func=lambda args, argv: self.mkdocs(mkdocs_serve_command, args, argv),
+        )
+
+        self.add_mkdocs_command_parser(
+            subparsers,
+            "build",
+            "execute mkdocs build",
+            func=lambda args, argv: self.mkdocs(mkdocs_build_command, args, argv),
+        )
+
+        dump_command = self.add_command_parser(subparsers, "dump", "dump site files to the dir", func=self.dump)
+        dump_command.add_argument(
+            "--output", required=False, type=directory, help="Output directory. Default - Current directory"
+        )
+
+        args, argv = parser.parse_known_args()
+
+        if not hasattr(args, "func"):
+            parser.print_help()
+            sys.exit(0)
+        try:
+            success, message = args.func(args, argv)
+            if not success:
+                print(message, file=sys.stderr)
+            elif message is not None:
+                print(message)
+        except Exception as e:  # pylint: disable=broad-exception-caught
+            self.logger.exception(f"FAIL! {e}")
+            success = False
+
+        sys.exit(0 if success else 1)
+
+    @staticmethod
+    def add_command_parser(subparsers, name, help_text, func):
+        command_parser = subparsers.add_parser(name, help=help_text)
+        command_parser.set_defaults(func=func, commandName=name)
+        return command_parser
+
+    @staticmethod
+    def add_mkdocs_command_parser(subparsers, name, help_text, func):
+        command_parser = add_command_parser(subparsers, name, help_text, func)
+        command_parser.add_argument("--local-docs", required=False, type=local_docs)
+        command_parser.add_argument("--site-root", required=False, type=directory)
+        return command_parser
+
+    def mkdocs(self, command, args, argv):
+
+        site_root_path = args.site_root
+        if site_root_path is None:
+            site_root_path = self.__default_site_root
+
+        self.logger.info(f"site root: {site_root_path}")
+        mkdocs_yaml_path = os.path.join(site_root_path, "mkdocs.yml")
+        if not os.path.isfile(mkdocs_yaml_path):
+            return False, "Site root does not have mkdocs.yml"
+        with open(mkdocs_yaml_path) as file:
+            mkdocs_yaml = yaml.safe_load(file)
+        plugins = mkdocs_yaml.get("plugins", [])
+        if not any("partial_docs" in plugin for plugin in plugins):
+            return False, f"{mkdocs_yaml_path} must define 'partial_docs' plugin"
+
+        if args.local_docs is not None:
+            plugin, docs_path = args.local_docs
+            PartialDocsPlugin.docs_path_overrides[plugin] = docs_path
+
+        current_dir = os.getcwd()
+        os.chdir(site_root_path)
+        try:
+            os.chdir(site_root_path)
+            Path(site_root_path).mkdir(parents=True, exist_ok=True)
+            command(argv)  # pylint: disable=too-many-function-args
+        finally:
+            os.chdir(current_dir)
+        return False, ""
+
+    def dump(self, args, argv):  # pylint: disable=unused-argument
+        output = args.output
+        if output is None:
+            output = os.getcwd()
+        output = normalize_path(output)
+
+        for path in glob.glob(os.path.join(self.__default_site_root, "**/*"), recursive=True):
+            path = normalize_path(path)
+            dest = os.path.relpath(path, self.__default_site_root)
+            dest = os.path.join(output, dest)
+            dest = normalize_path(dest)
+            if os.path.isdir(path):
+                os.makedirs(dest, exist_ok=True)
+            else:
+                os.makedirs(os.path.dirname(dest), exist_ok=True)
+                shutil.copy(path, dest)
+
+        return True, ""
+
+
+if __name__ == "__main__":
+    SiteEntryPoint("1.0", r"d:\CODE\cy\subsystems\documentation\docs-site-documentation-inceptum").run()

mkdocs_partial/templating/__init__.py

@@ -0,0 +1,5 @@
+import re
+
+PACKAGE_NAME_RESTRICTED_CHARS = re.compile(r"[^A-Za-z0-9+_-]")
+MODULE_NAME_RESTRICTED_CHARS = re.compile(r"[^a-z0-9+_]")
+PACKAGE_NAME = re.compile(r"^[A-Za-z0-9+_-]+$")

mkdocs_partial/templating/markdown_extension.py

@@ -0,0 +1,38 @@
+import re
+from html import escape
+from typing import Callable, Dict
+
+from mkdocs_partial.templating.templater_extension import TemplaterExtension
+
+
+class TemplaterMarkdownExtension(TemplaterExtension):
+    @property
+    def filters(self) -> Dict[str, Callable]:
+        yield "escape_markdown", self.escape_markdown
+        yield "escape_new_lines", self.escape_new_lines
+        yield "nowrap", self.nowrap
+        yield "table_safe", self.table_safe
+        yield "eclipse", self.eclipse
+        yield "remove_tags", self.remove_tags
+
+    def escape_markdown(self, text):
+        text = escape(str(text))
+        return text.replace("|", "|").replace("_", "_").replace("*", "*")
+
+    def escape_new_lines(self, text):
+        return text.replace("\r\n", "<br/>").replace("\n", "<br/>").rstrip("<br/>")
+
+    def nowrap(self, text):
+        return text.replace("-", "&#x2011;").replace(" ", "&#160;")
+
+    def table_safe(self, text):
+        return text.replace("|", "\\|")
+
+    def eclipse(self, value, length=48, add_spaces=False):
+        if len(value) > length:
+            return value[: length - 3] + "..."
+
+        return value.ljust(length) if add_spaces else value
+
+    def remove_tags(self, value):
+        return re.sub("\\[.*?\\]\\s*", "", value)

mkdocs_partial/templating/templater.py

@@ -0,0 +1,76 @@
+import os
+from abc import ABC
+from argparse import ArgumentError
+from io import StringIO
+from pathlib import Path
+from typing import Callable, Dict
+
+import jinja2
+
+from mkdocs_partial.templating.templater_extension import TemplaterExtension
+
+
+class Templater(ABC):
+    def __init__(self, templates_dir, template_filters: Dict[str, Callable] = None, output_path=None, **template_args):
+        if template_filters is None:
+            template_filters = {}
+        if output_path is None:
+            output_path = os.getcwd()
+        self.output_path = output_path
+        self.templates_dir = templates_dir
+        template_loader = jinja2.FileSystemLoader(searchpath=templates_dir)
+        self.__template_environment = jinja2.Environment(
+            loader=template_loader, trim_blocks=True, lstrip_blocks=False, newline_sequence="\r\n"
+        )
+        self.__template_args = template_args
+        filters = {}
+        filters.update(template_filters)
+        for name, method in filters.items():
+            self.__template_environment.filters[name] = method
+
+    def extend(self, extension: TemplaterExtension):
+        for name, method in extension.filters:
+            self.__template_environment.filters[name] = method
+        self.__template_args.update(extension.args)
+        return self
+
+    def write_template(self, template: str, /, *, path=None, **args):
+        if template is None or template == "":
+            raise ArgumentError(template, "template should not be None")
+        template_vars = {}
+        if path is None:
+            path = template
+        template_vars.update(args)
+        report_file = path
+        if not os.path.isabs(path):
+            report_file = os.path.normpath(os.path.join(self.output_path, path))
+        Path(os.path.dirname(report_file)).mkdir(parents=True, exist_ok=True)
+        with open(report_file, "w", encoding="utf-8") as file:
+            self.__template(template, file, **args)
+        return report_file
+
+    def template(self, template, **args):
+        stream = StringIO()
+        self.__template(template, stream, **args)
+        stream.seek(0)
+        return stream.read()
+
+    def template_string(self, template, **args):
+        stream = StringIO()
+        self.__template(template, stream, is_str=True, **args)
+        stream.seek(0)
+        return stream.read()
+
+    def __template(self, template, stream, is_str=False, **args):
+        template_vars = {}
+        if args is None:
+            args = {}
+        args = dict(args)
+        args.update(self.__template_args)
+        template_vars.update(args)
+        template = (
+            self.__template_environment.from_string(template)
+            if is_str
+            else self.__template_environment.get_template(template)
+        )
+        template.stream(template_vars).dump(stream)

mkdocs_partial/templating/templater_extension.py

@@ -0,0 +1,17 @@
+from abc import ABC
+from typing import Any, Callable, Dict
+
+
+class TemplaterExtension(ABC):
+
+    def __init__(self, **kwargs):
+        self.__args = kwargs
+        super().__init__()
+
+    @property
+    def filters(self) -> Dict[str, Callable]:
+        return {}
+
+    @property
+    def args(self) -> Dict[str, Any]:
+        return self.__args

mkdocs_partial/templating/version.py

@@ -0,0 +1,5 @@
+"""
+Version
+"""
+
+__version__ = "0.1.0"

mkdocs_partial/version.py

@@ -0,0 +1 @@
+__version__ = "1.2.1"

mkdocs_partial-1.2.1.dist-info/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2024 Exordis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mkdocs_partial-1.2.1.dist-info/METADATA

@@ -0,0 +1,31 @@
+Metadata-Version: 2.1
+Name: mkdocs-partial
+Version: 1.2.1
+Summary: Mkdocs Partial Documentation
+Author: Exorids
+Project-URL: Homepage, https://github.com/exordis/mkdocs-partial
+Project-URL: Documentation, https://docs.exordis.com/Partial%20Documentation/
+Keywords: mkdocs,partial
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+License-File: LICENSE
+Requires-Dist: setuptools <75,>=74
+Requires-Dist: PyYAML <6.1,>=6.0.1
+Requires-Dist: mkdocs <1.7,>=1.6
+Requires-Dist: python-frontmatter <1.2,>=1.1.0
+Requires-Dist: argparse <1.5,>=1.4
+Requires-Dist: packaging >=24.0
+Provides-Extra: lint
+Requires-Dist: black <25,>=24.8 ; extra == 'lint'
+Requires-Dist: flake8 <8.0.0,>=7.0.0 ; extra == 'lint'
+Requires-Dist: isort <6.0.0,>=5.13.0 ; extra == 'lint'
+Requires-Dist: pylint ==3.3.0 ; extra == 'lint'
+Provides-Extra: test
+Requires-Dist: pytest <8.0.0,>=7.1.3 ; extra == 'test'
+Requires-Dist: pytest-cov <4.0.0,>=3.0.0 ; extra == 'test'
+Requires-Dist: pytest-mock <4.0.0,>=3.0.0 ; extra == 'test'
+Requires-Dist: pytest-resource-path ==1.3.0 ; extra == 'test'
+
+Mkdocs Partial Documentation

mkdocs_partial-1.2.1.dist-info/RECORD

@@ -0,0 +1,41 @@
+mkdocs_partial/__init__.py,sha256=clmwB5riEm0TL650ufjrDAcyIHyKWpeG7rJzhWY_qus,1292
+mkdocs_partial/argparse_types.py,sha256=0_DEhGfbs8rCqGRnyMVInTuakfZ07_9-xLub_23H2rk,332
+mkdocs_partial/docs_package_plugin.py,sha256=OvkgIouMEFv_OsydmeFm3Mv289dTOHTBdBV1AKylR3k,9640
+mkdocs_partial/entry_point.py,sha256=RIjzz_YXPvy4dLTf7q4TwmoaPs2zKUHUqbrBKLe4iRo,7007
+mkdocs_partial/mkdcos_helpers.py,sha256=Ihi8Fxe2KiN6qGroaMHKl0XZSk9XRr6Q1E0HcCXOQBY,3681
+mkdocs_partial/partial_docs_plugin.py,sha256=CNgudgX8ztjITAAyPonc4smNUBIJlLFOIek19syN2a4,3743
+mkdocs_partial/site_entry_point.py,sha256=lmevOAab7VknT2Mo7biUuiiCk8Rj45VD78o-SgLkVTM,5696
+mkdocs_partial/version.py,sha256=Mlm4Gvmb_6yQxwUbv2Ksc-BJFXLPg9H1Vt2iV7wXrA4,22
+mkdocs_partial/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mkdocs_partial/integrations/macros_plugin_shim.py,sha256=FI1lwMDHhPTDvEs6RwPPScgkNrprgA24hX2Ys8RfXOg,1451
+mkdocs_partial/integrations/material_blog_integration.py,sha256=oyIAM69w9n5S8JSltHg7nX1KUIUDA-Htn67ny9BkLbk,6577
+mkdocs_partial/integrations/redirect_plugin_shim.py,sha256=l5rzNnYSDiBXe39zeKLamClTfS1beDFXLhYWPl26y8U,1057
+mkdocs_partial/integrations/spellcheck_plugin_shim.py,sha256=IDX_bdBxvbdH6fYTrcNRIIILjn0kOHMWM75GNVefnTE,1959
+mkdocs_partial/packages/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mkdocs_partial/packages/packager.py,sha256=hDThinVAyvufBr390rTZcpNyNHSSaQCb9s3vUkG58co,9358
+mkdocs_partial/packages/templates/docs-package/dist-info/METADATA.j2,sha256=jP5exCZ02fHV5CZUSOglXC1fpR1aOu2End2UF142MwU,200
+mkdocs_partial/packages/templates/docs-package/dist-info/WHEEL.j2,sha256=oqtHCHiufqw6DYjrSjrApk-sRVBDzXyYro5YVCSEvGE,83
+mkdocs_partial/packages/templates/docs-package/dist-info/entry_points.txt.j2,sha256=1W6F_2bOdyyYsND6ghRt53DkRpW3Ujv1x41wdfSTos4,66
+mkdocs_partial/packages/templates/docs-package/package/__init__.py.j2,sha256=tk9gDtreAfgnAcuBkmzAVKWiUaW-wDPltHV3PPgqzAM,88
+mkdocs_partial/packages/templates/docs-package/package/plugin.py.j2,sha256=Vn_ONwaJz5WRqsjbyc2zx-Va9RGZQQup8GNfObduTpA,379
+mkdocs_partial/packages/templates/docs-package/package/__pyinstaller/__init__.py.j2,sha256=n3qUujxBN7F1dvga4UNc5VQQ0L3GL4kp6ilu8Fbn-8E,75
+mkdocs_partial/packages/templates/docs-package/package/__pyinstaller/hook-{{module_name}}.py.j2,sha256=x5JKrRwq5aGIq-BbDMoWGS60ZEZM9MfWfr4J8fm6HpU,965
+mkdocs_partial/packages/templates/site-package/dist-info/METADATA.j2,sha256=jP5exCZ02fHV5CZUSOglXC1fpR1aOu2End2UF142MwU,200
+mkdocs_partial/packages/templates/site-package/dist-info/WHEEL.j2,sha256=oqtHCHiufqw6DYjrSjrApk-sRVBDzXyYro5YVCSEvGE,83
+mkdocs_partial/packages/templates/site-package/dist-info/entry_points.txt.j2,sha256=zeQVaJ8wUjDbFmvPJx1In2-zeCj-jObGpAsx5Xbz4ek,145
+mkdocs_partial/packages/templates/site-package/package/__init__.py.j2,sha256=tk9gDtreAfgnAcuBkmzAVKWiUaW-wDPltHV3PPgqzAM,88
+mkdocs_partial/packages/templates/site-package/package/__main__.py.j2,sha256=olncNMUUaIZ1L6b4QKd1Ep0czGiYH6_g-3VgFHUbF1U,94
+mkdocs_partial/packages/templates/site-package/package/entry_point.py.j2,sha256=n9-sPkBWLyYqpWFlxnTrOweC0NADh0JFArvkJ-bh570,332
+mkdocs_partial/packages/templates/site-package/package/__pyinstaller/__init__.py.j2,sha256=n3qUujxBN7F1dvga4UNc5VQQ0L3GL4kp6ilu8Fbn-8E,75
+mkdocs_partial/packages/templates/site-package/package/__pyinstaller/hook-{{module_name}}.py.j2,sha256=pyrikIqSRRbw7YNOnSpDVPYNxZjbXRbxatroyxM2skM,1021
+mkdocs_partial/templating/__init__.py,sha256=4w62VvjHdoB8ThB6Z6BLw61xP2p8rXjyfds-3vjnurg,185
+mkdocs_partial/templating/markdown_extension.py,sha256=j24tTTRZkS_kZt5hD7P-O3AaZHJYdURSzDv7purKZGI,1310
+mkdocs_partial/templating/templater.py,sha256=jFk-LRSnVrMyOZE46lDih-XOc4GTzZrOtb81jO27ovY,2893
+mkdocs_partial/templating/templater_extension.py,sha256=CqP092ZB3OCSCIZNSAJYwovicVjEkxUm3BdscvfycOc,359
+mkdocs_partial/templating/version.py,sha256=K1EbhMYUkog0O4znEW0NoISmA-SGFEjhlLvvOxTvdrc,39
+mkdocs_partial-1.2.1.dist-info/LICENSE,sha256=L2U87H2Agcp9ERUZyQ3u3GNzXlp5JBSom8QTRsvmDxI,1068
+mkdocs_partial-1.2.1.dist-info/METADATA,sha256=N8_QRXRbG7v0umAgC3BQv-HNF5ja1EUKzfunA3q18PM,1205
+mkdocs_partial-1.2.1.dist-info/WHEEL,sha256=R06PA3UVYHThwHvxuRWMqaGcr-PuniXahwjmQRFMEkY,91
+mkdocs_partial-1.2.1.dist-info/entry_points.txt,sha256=kl-tZYlorEy6jL1ua0YYFVw9suKUDBQM00D9BSLKpbs,220
+mkdocs_partial-1.2.1.dist-info/top_level.txt,sha256=Sgy37fgFOY3--xaLzfu5MAPTOUeUTbK-LOQ1K9xrNWw,15
+mkdocs_partial-1.2.1.dist-info/RECORD,,

mkdocs_partial-1.2.1.dist-info/WHEEL

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

mkdocs_partial-1.2.1.dist-info/entry_points.txt

@@ -0,0 +1,6 @@
+[console_scripts]
+mkdocs-partial = mkdocs_partial.entry_point:run
+
+[mkdocs.plugins]
+docs_package = mkdocs_partial.docs_package_plugin:DocsPackagePlugin
+partial_docs = mkdocs_partial.partial_docs_plugin:PartialDocsPlugin

mkdocs_partial-1.2.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+mkdocs_partial