mkdocs-apidescribed-plugin 1.1.0__tar.gz → 1.3.0__tar.gz

{mkdocs_apidescribed_plugin-1.1.0 → mkdocs_apidescribed_plugin-1.3.0}/.gitignore

@@ -8,3 +8,4 @@ __pycache__
 *.pyo
 *.egg-info
 
+*.lock

{mkdocs_apidescribed_plugin-1.1.0 → mkdocs_apidescribed_plugin-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: mkdocs-apidescribed-plugin
-Version: 1.1.0
+Version: 1.3.0
 Summary: mkdocs plugin to generate API documentation for Python programs
 Project-URL: Homepage, https://github.com/idlesign/mkdocs-apidescribed-plugin
 Project-URL: Documentation, https://mkdocs-apidescribed-plugin.readthedocs.org/

mkdocs_apidescribed_plugin-1.3.0/src/mkdocs_apidescribed/__init__.py

@@ -0,0 +1,2 @@
+
+VERSION = '1.3.0'

{mkdocs_apidescribed_plugin-1.1.0 → mkdocs_apidescribed_plugin-1.3.0}/src/mkdocs_apidescribed/config.py

@@ -7,6 +7,7 @@ log = get_plugin_logger(__name__)
 DEFAULT_CONFIG = {
     'debug': False,  # show traceback
     'skip': False,  # do not describe (allows instructions to be ignored)
+    'error': 'describe',  # error handling mode: ignore, describe, break
     'format': 'auto',  # docstrings format (sphinx, google, numpy)
 
     'heading_base': 2,  # headings base level
@@ -80,7 +81,15 @@ def config_merge(base: dict, *, upd: dict) -> dict:
     return out
 
 
-def get_config(src: str) -> dict:
-    parsed = config_parse(src)
-    merged = config_merge(DEFAULT_CONFIG, upd=parsed)
+def get_config(src: str, *, base: dict | None = None) -> dict:
+    """Returns configuration built from the default one,
+    updated with the given base (e.g. a global config),
+    updated with the options parsed from the given source.
+
+    :param src: Options source (YAML).
+
+    :param base: Base configuration to use instead of the default one.
+
+    """
+    merged = config_merge(config_merge(DEFAULT_CONFIG, upd=base or {}), upd=config_parse(src))
     return merged

{mkdocs_apidescribed_plugin-1.1.0 → mkdocs_apidescribed_plugin-1.3.0}/src/mkdocs_apidescribed/extension.py

@@ -4,7 +4,7 @@ from markdown import Extension
 from markdown.preprocessors import Preprocessor
 from mkdocs.plugins import get_plugin_logger
 
-from .config import get_config
+from .config import DEFAULT_CONFIG, get_config
 from .formatter import Formatter
 from .inspector import inspect
 
@@ -17,6 +17,10 @@ class ApidescribedProcessor(Preprocessor):
 
     cls_fmt = Formatter
 
+    def __init__(self, parser, *, global_config: dict | None = None):
+        super().__init__(parser)
+        self._global_config = global_config or {}
+
     @classmethod
     def process_instruction(cls, *, target: str, config: dict) -> list[str]:
         cls_fmt = cls.cls_fmt
@@ -72,13 +76,15 @@ class ApidescribedProcessor(Preprocessor):
                 else:
                     # end of an instruction options block
                     debug = False
+                    error_mode = "describe"
 
                     try:
                         target = instruction[0]
-                        config = get_config('\n'.join(instruction[1:]))
+                        config = get_config('\n'.join(instruction[1:]), base=self._global_config)
 
                         skip = config['skip']
                         debug = config['debug']
+                        error_mode = config['error']
 
                         if skip:
                             log.debug(f'Skipped instruction for: {target}')
@@ -86,10 +92,14 @@ class ApidescribedProcessor(Preprocessor):
                         else:
                             to_add = process_instruction(target=target, config=config)
 
-                    except Exception as e:
+                    except Exception as error:
+
+                        if error_mode == "break":
+                            raise
 
-                        to_add = [Formatter.format_error(e, instruction=instruction, debug=debug)]
-                        log.exception('Automated API documentation error')
+                        if error_mode == "describe":
+                            to_add = [Formatter.format_error(error, instruction=instruction, debug=debug)]
+                            log.exception('Automated API documentation error')
 
                     finally:
                         instruction.clear()
@@ -101,9 +111,15 @@ class ApidescribedProcessor(Preprocessor):
 
 class ApiDescribedExtension(Extension):
 
+    def __init__(self, **kwargs):
+        # Predeclare known options to allow arbitrary values via setConfig.
+        self.config = {key: [val, ""] for key, val in DEFAULT_CONFIG.items()}
+        super().__init__(**kwargs)
+
     def extendMarkdown(self, md):
         md.registerExtension(self)
-        md.preprocessors.register(ApidescribedProcessor(md.parser), "apidescribed", 110)
+        md.preprocessors.register(
+            ApidescribedProcessor(md.parser, global_config=self.getConfigs()), "apidescribed", 110)
 
 
 def makeExtension(**kwargs):

mkdocs_apidescribed_plugin-1.3.0/src/mkdocs_apidescribed/plugin.py

@@ -0,0 +1,46 @@
+import mkdocs
+from material.extensions.emoji import twemoji, to_svg
+from mkdocs.config import config_options
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.plugins import get_plugin_logger
+
+log = get_plugin_logger(__name__)
+
+
+class ApiDescribedPlugin(mkdocs.plugins.BasePlugin):
+
+    config_scheme = (
+        ("config", config_options.Type(dict, default={})),
+    )
+
+    _required_extensions = [
+        'mkdocs_apidescribed.extension',  # this is our extension
+        'admonition',  # nice admonitions
+        'md_in_html',  # for proper indentation
+        'pymdownx.details',  # collapsible blocks
+        'pymdownx.superfences',  # for block embedding
+        'pymdownx.emoji',  # for icons
+    ]
+
+    def on_config(self, config: MkDocsConfig) -> MkDocsConfig:
+        extensions = config['markdown_extensions']
+        current_extensions = set(extensions)
+
+        for ext in self._required_extensions:
+            if ext not in current_extensions:
+                extensions.append(ext)
+
+        mdx_conf = config['mdx_configs'].setdefault('mkdocs_apidescribed.extension', {})
+        mdx_conf.update(self.config['config'])
+
+        icons_conf = config['mdx_configs'].setdefault('pymdownx.emoji', {})
+        icons_conf['emoji_index'] = twemoji
+        icons_conf['emoji_generator'] = to_svg
+
+        theme_features = config['theme']._vars.setdefault('features', [])
+
+        feature_annotate = 'content.code.annotate'
+        if feature_annotate not in theme_features:
+            theme_features.append(feature_annotate)
+
+        return config

mkdocs_apidescribed_plugin-1.1.0/src/mkdocs_apidescribed/__init__.py

@@ -1,2 +0,0 @@
-
-VERSION = '1.1.0'

mkdocs_apidescribed_plugin-1.1.0/src/mkdocs_apidescribed/plugin.py

@@ -1,8 +0,0 @@
-import mkdocs
-from mkdocs.plugins import get_plugin_logger
-
-log = get_plugin_logger(__name__)
-
-
-class ApiDescribedPlugin(mkdocs.plugins.BasePlugin):
-    ...