mkdocs-apidescribed-plugin 0.1.0__py3-none-any.whl

mkdocs_apidescribed/__init__.py

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

mkdocs_apidescribed/config.py

@@ -0,0 +1,84 @@
+import yaml
+from mkdocs.plugins import get_plugin_logger
+
+log = get_plugin_logger(__name__)
+
+
+DEFAULT_CONFIG = {
+    'debug': False,  # show traceback
+    'skip': False,  # do not describe (allows instructions to be ignored)
+    'format': 'auto',  # docstrings format (sphinx, google, numpy)
+
+    'heading_base': 2,  # headings base level
+    'autolinks': True,  # automatically create hyperlinks
+    'categorize': True,  # show symbol types (categories) titles
+
+    'location': {
+        # signature block title options
+        # hidden - do not show the block
+        # module - show module "path"
+        # file - show filepath
+        'mode': 'hidden',
+        'line': False,  # show line number of source file
+    },
+    'icons': {
+        'attr': ':material-alpha:',  # for attributes
+        'func': ':material-function:',  # for functions
+        'cls': ':material-delta:',  # for classes
+        'property': ':material-alpha-p-box-outline:',  # for class properties
+        'classmethod': ':material-alpha-c-box-outline:',  # for class properties
+        'staticmethod': ':material-alpha-s-box-outline:',  # for class properties
+        'inherited': ':material-subdirectory-arrow-left:',  # for class inherited items
+        'raises': ':material-lightning-bolt:',  # for descriptions of raised exceptions
+        'returns': ':material-arrow-right-thin:',  # for descriptions of returned value
+    },
+
+    'undocumented': False,  # describe items without docstrings
+    'types': [
+        # symbol types to describe (order respected)
+        'attributes',
+        'functions',
+        'classes',
+    ],
+    'ignore': [
+        # patterns of symbol names to ignore
+        '_*',
+    ],
+    'only': [
+        # symbol names to describe (others will be ignored)
+    ],
+}
+"""Default configuration for mkdocs-apidescribed."""
+
+
+def config_parse(src: str) -> dict:
+    try:
+        cfg = yaml.load(src, yaml.SafeLoader)
+    except yaml.MarkedYAMLError:
+        log.exception('Unable to parse options.')
+        cfg = {}
+
+    return cfg or {}
+
+
+def config_merge(base: dict, *, upd: dict) -> dict:
+    out = {}
+
+    for key, val in base.items():
+
+        if (upd_val := upd.get(key)) is not None:
+
+            if isinstance(val, dict) and isinstance(upd_val, dict):
+                upd_val = config_merge(val, upd=upd_val)
+
+            val = upd_val
+
+        out[key] = val
+
+    return out
+
+
+def get_config(src: str) -> dict:
+    parsed = config_parse(src)
+    merged = config_merge(DEFAULT_CONFIG, upd=parsed)
+    return merged

mkdocs_apidescribed/extension.py

@@ -0,0 +1,104 @@
+import re
+
+from markdown import Extension
+from markdown.preprocessors import Preprocessor
+from mkdocs.plugins import get_plugin_logger
+
+from .config import get_config
+from .formatter import Formatter
+from .inspector import inspect
+
+log = get_plugin_logger(__name__)
+
+
+class ApidescribedProcessor(Preprocessor):
+
+    RE_START = re.compile(r'^::: apidescribed:(.*)')
+
+    cls_fmt = Formatter
+
+    @classmethod
+    def process_instruction(cls, *, target: str, config: dict) -> list[str]:
+        cls_fmt = cls.cls_fmt
+        out = []
+        last_type = ''
+
+        root, symbols = inspect(target, types=config['types'], ignore=config['ignore'], only=config['only'])
+        formatter = cls_fmt(symbol=root, config=config)
+
+        if prolog := formatter.run():
+            out.append(prolog)
+
+        for symbol in symbols:
+            formatter = cls_fmt(symbol=symbol, config=config)
+
+            if symbol.depth == 0:
+                if last_type != symbol.type.name and (categorized := formatter.format_category()):
+                    out.append(categorized)
+
+                last_type = symbol.type.name
+
+            formatted = formatter.run()
+            out.append(formatted)
+
+        return out
+
+    def run(self, lines: list[str]) -> list[str]:
+        out = []
+
+        re_start = self.RE_START
+        process_instruction = self.process_instruction
+        instruction = []
+
+        for line in lines:
+
+            to_add = [line]
+
+            if matched := re_start.search(line):
+                instruction.append(matched[1].strip())
+                to_add = []
+
+            elif instruction:
+                if line.startswith('    '):
+                    # new option for instruction
+                    instruction.append(line)
+                    to_add = []
+                else:
+                    # end of an instruction options block
+                    debug = False
+
+                    try:
+                        target = instruction[0]
+                        config = get_config('\n'.join(instruction[1:]))
+
+                        skip = config['skip']
+                        debug = config['debug']
+
+                        if skip:
+                            log.debug(f'Skipped instruction for: {target}')
+
+                        else:
+                            to_add = process_instruction(target=target, config=config)
+
+                    except Exception as e:
+
+                        to_add = [Formatter.format_error(e, instruction=instruction, debug=debug)]
+                        log.exception('Automated API documentation error')
+
+                    finally:
+                        instruction.clear()
+
+            out.extend(to_add)
+
+        return out
+
+
+class ApiDescribedExtension(Extension):
+
+    def extendMarkdown(self, md):
+        md.registerExtension(self)
+        md.preprocessors.register(ApidescribedProcessor(md.parser), "apidescribed", 110)
+
+
+def makeExtension(**kwargs):
+    return ApiDescribedExtension(**kwargs)

mkdocs_apidescribed/formatter.py

@@ -0,0 +1,304 @@
+import re
+from textwrap import indent, dedent
+from traceback import format_exc
+from typing import Any
+
+import griffe
+from mkdocs.plugins import get_plugin_logger
+
+from .inspector import Symbol, SymbolType
+from .parsers import DocstrParser, Block
+
+log = get_plugin_logger(__name__)
+
+RE_LINK = re.compile(
+    r'https?://(www\.)?[A-z0-9@:%.-_+~#=]{1,256}\.[A-z0-9()]{1,6}\b([A-z0-9()@:%-_+.~#?&/=]*)'
+)
+
+
+class Formatter:
+
+    category_titles = {
+        SymbolType.attr: 'Attributes',
+        SymbolType.func: 'Functions',
+        SymbolType.cls: 'Classes',
+    }
+
+    @classmethod
+    def format_error(cls, exc: Exception, *, instruction: list[str], debug: bool = False) -> str:
+
+        def indent_raw(val: str) -> str:
+            return f'    ```\n{indent(val, prefix='    ')}\n    ```\n'
+
+        lines = [
+            f'??? failure "Automated documentation error: {exc.__class__.__name__}"',
+            '    **Configuration**',
+            indent_raw("\n".join(instruction)),
+            f'    **Error**',
+            indent_raw(f'{exc}\n\n{format_exc() if debug else ""}'),
+        ]
+
+        return '\n'.join(lines)
+
+    @classmethod
+    def format_block_admonition(cls, block: Block) -> str:
+        return f'!!! {block.marker}\n{cls.reindent(block)}'
+
+    @classmethod
+    def format_block_code(cls, block: Block) -> str:
+        return f'```{block.value}\n' + dedent('\n'.join(block.addition)) + '\n```'
+
+    @classmethod
+    def format_block_version(cls, block: Block) -> str:
+        return ''
+
+    @classmethod
+    def reindent(cls, src: Any) -> str:
+        return indent(dedent(f'{src}'), '    ')
+
+    def __init__(self, *, symbol: Symbol, config: dict):
+        self.symbol = symbol
+        self.config = config
+
+        categorize = config['categorize']
+        self.categorize = categorize
+
+        heading_base = config['heading_base']
+        self.heading_base = heading_base
+        self.heading_level = heading_base + 1 if categorize else heading_base
+
+        self.docstr = DocstrParser.parse(self.symbol.docstr, config=config, formatter=self)
+
+    def signature_reconstruct_params(self) -> dict[str, tuple[str, str]]:
+        docstring = self.docstr
+
+        params = {}
+
+        for param in self.symbol.params:
+            param_name = param.name
+            param_str = param_name
+            param_note = docstring.params.get(param_str, '')
+
+            default = param.default
+            annotation = param.annotation
+
+            match param.kind:
+                case griffe.ParameterKind.var_positional:
+                    param_str = f'*{param_str}'
+                    default = False
+
+                case griffe.ParameterKind.var_keyword:
+                    param_str = f'**{param_str}'
+                    default = False
+
+            if annotation:
+                if default:
+                    annotation = f'{annotation} '
+                param_str = f'{param_str}: {annotation}'
+
+            if default:
+                if annotation:
+                    default = f' {default}'
+                param_str = f'{param_str}={default}'
+
+            params[param_name] = (f'{param_str},', param_note)
+
+        return params
+
+    def signature_build(self, params: dict) -> tuple[str, list[str]]:
+        symbol = self.symbol
+        reindent = self.reindent
+
+        notes_counter = 0
+        param_strings = []
+        param_notes = []
+
+        for param_str, param_note in params.values():
+            postfix = ''
+
+            if param_note:
+                notes_counter += 1
+                postfix = f' # ({notes_counter})!'  # add annotation index
+                param_notes.append(f'{notes_counter}. {reindent(param_note)}\n')
+
+            param_strings.append(f'{param_str}{postfix}')
+
+        def get_signature() -> str:
+            chunks = [
+                '.' if symbol.is_class_member else '',
+                f'{symbol.name}(',
+                f'{joiner}{indented}',
+                f'{joiner}{indented}'.join(param_strings).replace(',', ', ').rstrip(', '),
+                f'{joiner})',
+            ]
+
+            if symbol.type == SymbolType.func and (returns := symbol.returns):
+                chunks.extend(f' -> {returns}')
+
+            return ''.join(chunks)
+
+        indented = '    '
+        joiner = '\n'
+
+        oneline = not len(param_notes)
+
+        if len(get_signature()) > 80:
+            oneline = False
+
+        if oneline:
+            indented = ''
+            joiner = ''
+
+        return get_signature(), param_notes
+
+    def handle_opt_location(self) -> str:
+        symbol = self.symbol
+        caption = ''
+
+        if location := self.config['location']:
+
+            match location['mode']:
+                case 'module':
+                    caption = f'{symbol.path}'.rpartition('.')[0]
+
+                case 'file':
+                    caption = f'{symbol.fpath}'
+
+            if caption and location['line']:
+                caption = f'{caption}:{symbol.line_start}'
+
+        return caption
+
+    def format_category(self) -> str:
+
+        if self.categorize and (category := self.category_titles.get(self.symbol.type)):
+            return f'{"#" * self.heading_base} {category}\n'
+
+        return ''
+
+    def format_signature(self) -> str:
+        symbol = self.symbol
+        param_notes = []
+
+        def get_signature():
+            return self.signature_build(self.signature_reconstruct_params())
+
+        match symbol.type:
+            case SymbolType.func | SymbolType.cls:
+                signature, param_notes = get_signature()
+
+            case SymbolType.attr:
+                if symbol.is_property:
+                    signature, param_notes = get_signature()
+
+                else:
+                    signature = (
+                        ('.' if symbol.is_class_member else '') +
+                        symbol.source
+                    )
+
+            case _:
+                signature = ''
+
+        if not signature:
+            return ''
+
+        caption = self.handle_opt_location()
+        if caption:
+            caption = f'title="{caption}"'
+
+        lines = [
+            f'\n``` py {caption}\n{signature}\n```\n',
+            # param descriptions block
+            *param_notes,
+        ]
+
+        return '\n'.join(lines)
+
+    def format_description(self) -> str:
+        docstring = self.docstr
+
+        text = docstring.text
+
+        text = f'{text}\n'
+
+        icons = self.config['icons']
+
+        if raised := docstring.raises:
+            raises = '\n\n'.join(
+                f'{icons["raises"]} `{raised_key}` {raised_val}'
+                for raised_key, raised_val in raised.items()
+            )
+            text = f'{text}\n{raises}\n'
+
+        if returns := docstring.returns:
+            returns = '\n\n'.join(
+                f'{icons["returns"]} {returned}'
+                for returned in returns
+            )
+            text = f'{text}\n{returns}\n'
+
+        return text
+
+    def format_title(self) -> str:
+        symbol = self.symbol
+        icons = self.config['icons']
+
+        icon_before = icons.get(symbol.type.name, '')
+        icons_after = []
+
+        if symbol.is_inherited:
+            icons_after.append(icons['inherited'])
+
+        if symbol.is_property:
+            icons_after.append(icons['property'])
+
+        if symbol.is_classmethod:
+            icons_after.append(icons['classmethod'])
+
+        if symbol.is_staticmethod:
+            icons_after.append(icons['staticmethod'])
+
+        title = (
+            f'{"#" * (self.heading_level + symbol.depth)} '
+            f'{icon_before} {symbol.name} {" ".join(icons_after)}\n'
+        )
+
+        return title
+
+    def indent(self, *, title: str, body: str) -> str:
+
+        left = '<div style="margin-left:1.8em" markdown>'
+        right = '</div>'
+
+        depth = self.symbol.depth
+
+        indented = (
+            (left * depth) +
+            title + (left + body + right) +
+            (right * depth)
+        )
+
+        return indented
+
+    def run(self) -> str:
+
+        signature = self.format_signature()
+
+        out = [
+            signature,
+            self.format_description(),
+        ]
+
+        out = '\n'.join(out)
+
+        if signature:
+            out = self.indent(title=self.format_title(), body=out)
+
+        if out.strip():
+            out = f'{out}\n----'
+
+        if self.config['autolinks']:
+            out = RE_LINK.sub(r'<\g<0>>', out)
+
+        return out

mkdocs_apidescribed/inspector.py

@@ -0,0 +1,205 @@
+from copy import deepcopy
+from dataclasses import dataclass
+from enum import Enum
+from fnmatch import fnmatch
+from typing import Any
+
+import griffe
+from mkdocs.plugins import get_plugin_logger
+
+log = get_plugin_logger(__name__)
+
+
+class SymbolType(Enum):
+    attr = 1
+    func = 2
+    cls = 3
+    module = 4
+
+
+@dataclass
+class Symbol:
+
+    depth: int
+    raw: Any
+    type: SymbolType
+    name: str
+    source: str
+    docstr: griffe.Docstring
+    path: str
+    fpath: str
+    params: griffe.Parameters | None
+    returns: str
+    line_start: int = None
+    line_end: int = None
+
+    @property
+    def is_property(self) -> bool:
+        return 'property' in self.raw.labels
+
+    @property
+    def is_inherited(self) -> bool:
+        return self.raw.inherited
+
+    @property
+    def is_class_member(self) -> bool:
+        return self.raw.parent.is_class
+
+    @property
+    def is_classmethod(self) -> bool:
+        return 'classmethod' in self.raw.labels
+
+    @property
+    def is_staticmethod(self) -> bool:
+        return 'staticmethod' in self.raw.labels
+
+
+def simplify_args(symb: griffe.Object, parameters: griffe.Parameters):
+    # drop self, cls
+    if symb.is_class or symb.parent.is_class:
+        if parameters._params:
+            parameters = deepcopy(parameters)
+            # Exceptions can have no params
+            parameters._params.pop(0)
+    return parameters
+
+
+def get_symbol(
+    obj: griffe.Object,
+    *,
+    types: list[str] = None,
+    undocumented: bool = False,
+    ignore: list[str] = None,
+    only: set[str] = None,
+    depth: int = 0,
+) -> tuple[Symbol, list[Symbol]] | None:
+
+    symbol_type = 0
+    symbols_sub = []
+    types = types or []
+
+    params = getattr(obj, 'parameters', [])
+    returns = getattr(obj, 'returns', None)
+
+    if obj.is_attribute:
+        symbol_type = SymbolType.attr
+
+    elif obj.is_module:
+        symbol_type = SymbolType.module
+
+    elif obj.is_function:
+        symbol_type = SymbolType.func
+        params = simplify_args(obj, params)
+
+    elif obj.is_class:
+        symbol_type = SymbolType.cls
+        params = simplify_args(obj, params)
+
+        symbols_sub = get_symbols(
+            obj,
+            types=types,
+            undocumented=undocumented,
+            ignore=ignore,
+            only=only,
+            depth=depth + 1
+        )
+
+    if not symbol_type:
+        log.error(f'Unsupported symbol type: {obj}. Skipped.')
+        return
+
+    symbol = Symbol(
+        depth=depth,
+        raw=obj,
+        type=symbol_type,
+        name=obj.name,
+        source=obj.source,
+        docstr=obj.docstring,
+        path=obj.path,
+        fpath=f'{obj.relative_package_filepath}',
+        params=params,
+        returns=returns,
+        line_start=obj.lineno,
+        line_end=obj.endlineno,
+    )
+    return symbol, symbols_sub
+
+
+def get_symbols(
+    container: griffe.Object,
+    *,
+    types: list[str],
+    undocumented: bool = False,
+    ignore: list[str] = None,
+    only: set[str] = None,
+    depth: int = 0
+) -> list[Symbol]:
+
+    symbols = []
+    ignore = ignore or []
+    only = only or set()
+
+    for key in types:
+
+        for _, symbol_raw in sorted(getattr(container, key).items(), key=lambda item: item[0]):
+
+            if not depth and symbol_raw.is_alias:
+                # hide imported from other modules
+                # but preserve class members inherited from base
+                continue
+
+            name = symbol_raw.name
+
+            docstring = symbol_raw.docstring
+            skip = False
+
+            if docstring is None and not undocumented:
+                continue
+
+            if only:
+                skip = name not in only
+
+            else:
+                for rule in ignore:
+                    if fnmatch(name, rule):
+                        skip = True
+                        break
+
+            if skip:
+                continue
+
+            symbol, symbols_sub = get_symbol(
+                symbol_raw,
+                types=types,
+                undocumented=undocumented,
+                ignore=ignore,
+                only=only,
+                depth=depth,
+            )
+
+            if symbol:
+                symbols.append(symbol)
+
+            if symbols_sub:
+                symbols.extend(symbols_sub)
+                # symbols_sub.clear()
+
+    return symbols
+
+
+def inspect(
+        target: str,
+        *,
+        types: list[str],
+        undocumented: bool = False,
+        ignore: list[str],
+        only: list[str]
+) -> tuple[Symbol, list[Symbol]]:
+
+    log.info(f'Getting API information for: {target} ...')
+    obj = griffe.load(target)
+
+    root, _ = get_symbol(obj)
+    symbols = get_symbols(obj, types=types, undocumented=undocumented, ignore=ignore, only=set(only))
+
+    return root, symbols

mkdocs_apidescribed/parsers.py

@@ -0,0 +1,229 @@
+import re
+from collections import defaultdict
+from dataclasses import dataclass, field
+from textwrap import dedent
+from typing import TYPE_CHECKING
+
+import griffe
+
+if TYPE_CHECKING:
+    from .formatter import Formatter
+
+
+@dataclass
+class Docstring:
+
+    text: str = ''
+    params: dict[str, str] = field(default_factory=dict)
+    returns: list[str] = field(default_factory=list)
+    raises: dict[str, str] =  field(default_factory=dict)
+
+
+class Block:
+
+    unmarked: str = '_unmarked'
+
+    def __init__(self, marker: str = '', arg: str = '', value: str = ''):
+        self.marker = marker or self.unmarked
+        self.arg = arg.strip()
+        self.value = value
+        self.addition = []
+
+    def __str__(self):
+        prefix = f'{value}\n' if (value := self.value) else ''
+        return prefix + '\n'.join(self.addition)
+
+    @property
+    def is_marked(self) -> bool:
+        return self.marker != self.unmarked
+
+    def contribute(self, val: str):
+        self.addition.append(val)
+
+
+class DocstrParser:
+    alias: str = ''
+
+    registry: dict[str, type['DocstrParser']] = {}
+
+    @classmethod
+    def parse(cls, docstr: griffe.Docstring | None, *, config: dict, formatter: 'Formatter') -> Docstring:
+
+        value = getattr(docstr, 'value', None) or ''
+        docstring = Docstring(text=f'{value}')
+
+        if value:
+            preferred_parser = config['format']
+
+            parser = DocstrParser.registry.get(preferred_parser)
+            parsers = [parser] if parser else DocstrParser.registry.values()
+
+            for parser_cls in parsers:
+                parser = parser_cls(value, config=config, formatter=formatter)
+
+                if (result := parser.run()) and parser.markers_detected:
+                    docstring = result
+                    break
+
+        return docstring
+
+    def __init_subclass__(cls):
+        alias = cls.alias
+        registry = cls.registry
+
+        assert alias
+        assert alias not in registry
+
+        super().__init_subclass__()
+
+        registry[alias] = cls
+
+    def __init__(self, src: str, *, config: dict, formatter: 'Formatter'):
+        self.src = src
+        self.config = config
+        self.markers_detected = False
+        self.formatter = formatter
+
+    def run(self) -> Docstring | None:
+        return self._parse(self.src)
+
+    def postprocess(self, text: str) -> str:
+        return text
+
+    def _parse(self, value: str) -> Docstring | None:  # pragma: nocover
+        return
+
+    def to_dict(self, blocks: list[Block]) -> dict[str, str]:
+        result = {
+            block.arg: self.postprocess(f'{block}')
+            for block in blocks
+        }
+        return result
+
+    def to_list(self, blocks: list[Block]) -> list[str]:
+        return [self.postprocess(f'{block}'.strip()) for block in blocks]
+
+
+class SphinxParser(DocstrParser):
+    alias: str = 'sphinx'
+
+    re_markers = re.compile(
+        r':(?P<marker>param|type|raises|return|rtype)'
+        r'(?P<arg>[^:]*):\s*(?P<value>.*)'
+    )
+
+    re_directives = re.compile(
+        r'\.\. (?P<marker>note|warning|code-block|versionadded|versionchanged|deprecated)'
+        r'(?P<arg>[^:]*)::\s*(?P<value>.*)'
+    )
+
+    def postprocess(self, text: str) -> str:
+        text = super().postprocess(text)
+        formatter = self.formatter
+
+        if (split := text.splitlines()) and len(split) > 1:
+            # nested indented block (e.g. in param descriptions)
+            # reindent with prefix from 2nd line
+            line_two = split[1]
+            prefix = ' ' * (len(line_two) - len(line_two.lstrip(' ')))
+            text = dedent('\n'.join([
+                f'{prefix}{split[0].lstrip()}',
+                *split[1:]
+            ]))
+
+        _, processed = self.parse_blocks(
+            pattern=self.re_directives,
+            value=text,
+        )
+
+        lines = []
+
+        for block in processed:
+            if block.is_marked:
+                match block.marker:
+                    case 'versionadded' | 'versionchanged' | 'deprecated':
+                        block = formatter.format_block_version(block)
+
+                    case 'note' | 'warning':
+                        block = formatter.format_block_admonition(block)
+
+                    case 'code-block':
+                        block = formatter.format_block_code(block)
+
+            lines.append(f'{block}')
+
+        return '\n'.join(lines)
+
+    def parse_blocks(
+            self,
+            *,
+            pattern: re.Pattern,
+            value: str,
+    ) -> tuple[dict[str, list[Block]], list[Block]]:
+
+        blocks: dict[str, list[Block]] = defaultdict(list)
+        block_last: Block | None = None
+        marker_detected = False
+
+        processed = []
+
+        for line in value.splitlines():
+
+            is_empty = len(line.strip()) == 0
+
+            if block_last:
+                if line.startswith(' ') or is_empty:
+                    # must be a continuation of a block
+                    block_last.contribute(line)
+                    continue
+
+                # previous block ended
+                processed.append(block_last)
+                block_last = None
+
+            if matched := pattern.match(line):
+                marker_detected = True
+                marker = matched.group('marker')
+
+                arg = matched.group('arg')
+                val = matched.group('value')
+
+                block = Block(marker, arg, val.strip())
+                blocks[marker].append(block)
+                block_last = block
+
+            else:
+                block = Block()
+                block.contribute(line)
+                blocks[Block.unmarked].append(block)
+                processed.append(block)
+
+        if block_last:
+            # block in the last line
+            processed.append(block_last)
+
+        self.markers_detected = self.markers_detected or marker_detected
+
+        return blocks, processed
+
+    def _parse(self, value: str) -> Docstring | None:
+
+        blocks, processed = self.parse_blocks(
+            pattern=self.re_markers,
+            value=value,
+        )
+
+        return Docstring(
+            text=self.postprocess('\n'.join(map(str, blocks[Block.unmarked]))),
+            params=self.to_dict(blocks['param']),
+            returns=self.to_list(blocks['return']),
+            raises=self.to_dict(blocks['raises']),
+        )
+
+
+class GoogleParser(DocstrParser):
+    alias: str = 'google'
+
+
+class NumpyParser(DocstrParser):
+    alias: str = 'numpy'

mkdocs_apidescribed/plugin.py

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

mkdocs_apidescribed/probe.py

@@ -0,0 +1,174 @@
+"""This is a module description.
+
+This takes several lines and contains formatted text.
+
+https://github.com/idlesign/mkdocs-apidescribed-plugin
+
+!!! note
+    This text is an admonition.
+
+.. warning:: This is a reStructuredText mixed warning.
+"""
+from os import environ
+
+from markdown.util import deprecated
+
+CONSTANT: int = 1
+"""Constant description."""
+
+ENVIRON = environ
+"""Alias description."""
+
+
+def undocumented():
+    pass
+
+
+def _hidden():
+    """Hide it."""
+
+
+def just_ignore_that():
+    """Ignore it."""
+
+
+def myfunc_rst(
+    a: list[str],
+    b: int = 0,
+    *args,
+    another: str,
+    **kwargs
+) -> bool:
+    """Function description.
+    This one is split into several lines
+    yet supposes a single sentence.
+
+    Uses reStructuredText markup for signature description.
+
+    See: https://github.com/idlesign/mkdocs-apidescribed-plugin
+
+    .. note::
+        Some note here.
+
+    .. code-block:: bash
+        cd ~
+        touch this/
+
+    :param a: comment for a
+        .. versionadded:: 2.5
+            Add this.
+
+        .. versionchanged:: 2.5
+            Something has changed.
+
+    :type a: List[str], optional
+    :param b: hint for b
+        Several lines.
+
+        .. warning::
+            Some warning
+
+        Another line.
+        https://github.com/idlesign/mkdocs-apidescribed-plugin
+    :param args: info for args
+    :param another: text for another
+        .. deprecated:: 3.1
+            Use something instead.
+
+    :param kwargs: description for kwargs
+
+    :raises ValueError: If something happens
+    :raises KeyError: If something other happens
+
+    :return: This is returned
+    :return: This is also returned
+    :rtype: bool
+
+    """
+
+
+def myfunc_google(q: str, w: int, e: list, **kwargs) -> bool:
+    """Function description.
+
+    Uses Google markup for signature description.
+
+    Note:
+        Some note for you.
+
+    Args:
+        q (str): Param q
+        w: Param w
+        e: Param e
+        **kwargs: Keyword parameters
+
+    Yields:
+        int: This one
+
+    Returns:
+        bool: True if successful, False otherwise.
+
+        Even more text for return description.
+
+    Raises:
+        AttributeError: Can raise
+            this in some cases.
+        ValueError: If something.
+
+    Examples:
+        This is an example.
+        Multiple Lines.
+
+    """
+
+
+class MyBaseClass:
+    """Base class description."""
+
+    base_attr: str = "base_attr value"
+    """Base attr description."""
+
+    @classmethod
+    def method_cl(cls, arg1: str):
+        """Class method."""
+
+    @staticmethod
+    def method_st(cls, val):
+        """Static method."""
+
+    def __init__(self, in_a: int):
+        """Base __init__ description."""
+
+    def __call__(self, in_b: int):
+        """Base __call__ description."""
+
+    @property
+    def prop_a(self) -> str:
+        """Property A."""
+
+    @prop_a.setter
+    def _prop_a_set(self, val: int) -> str:
+        """Property A setter."""
+
+    def __str__(self):
+        """Specialized. To string."""
+
+    def method_a(self, a=1):
+        """Base method_a description."""
+        return True
+
+
+class MySubClass(MyBaseClass):
+    """Sub class description."""
+
+    sub_attr = "sub_attr value"
+    """Sub attr description."""
+
+    @deprecated('This one is deprecated.')
+    def method_sub_b(
+        self,
+        a: str,
+        b: int,
+        d: float,
+    ) -> str:
+        """Sub method_sub_b description."""
+        return ''

mkdocs_apidescribed_plugin-0.1.0.dist-info/METADATA

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: mkdocs-apidescribed-plugin
+Version: 0.1.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/
+Author-email: Igor Starikov <idlesign@yandex.ru>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: api,mkdocs,plugin
+Requires-Python: >=3.10
+Requires-Dist: griffe
+Requires-Dist: mkdocs
+Requires-Dist: pyyaml
+Description-Content-Type: text/markdown
+
+# mkdocs-apidescribed-plugin
+
+https://github.com/idlesign/mkdocs-apidescribed-plugin
+
+[![PyPI - Version](https://img.shields.io/pypi/v/mkdocs-apidescribed-plugin)](https://pypi.python.org/pypi/mkdocs-apidescribed-plugin)
+[![License](https://img.shields.io/pypi/l/mkdocs-apidescribed-plugin)](https://pypi.python.org/pypi/mkdocs-apidescribed-plugin)
+[![Coverage](https://img.shields.io/coverallsCoverage/github/idlesign/mkdocs-apidescribed-plugin)](https://coveralls.io/r/idlesign/mkdocs-apidescribed-plugin)
+
+## Description
+
+*mkdocs plugin to generate API documentation for Python programs*
+
+* Made to autodocument Python code
+* Plays well with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
+* Configurable
+* Easy to use
+
+Just add ``::: apidescribed:`` directive into your documentation followed by a module path:
+
+```md title="index.md"
+This is my documentation
+
+::: apidescribed: somepackage.somemodule
+
+```
+
+## Documentation
+
+https://mkdocs-apidescribed-plugin.readthedocs.org/

mkdocs_apidescribed_plugin-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+mkdocs_apidescribed/__init__.py,sha256=2FRI0QQVpqa9D3Ny5p2lmon3dWjttDU7YivT4wXMJlM,19
+mkdocs_apidescribed/config.py,sha256=3P5OpESEg5FQMG0FDScVCoM6HJE1yJwu3FxEetH8L2Y,2529
+mkdocs_apidescribed/extension.py,sha256=3iBv7dQr9dOBwqssimo1J3C_R5O8kmq7HUiuzk5o0uY,2980
+mkdocs_apidescribed/formatter.py,sha256=ONVHitfZ0U8MyeRygy1-v9QIdIsXqvc5fv_T8qbfgEw,8387
+mkdocs_apidescribed/inspector.py,sha256=uovf-2BQkoD8O2DXV0RLSvPT_PMIg6qWUAVXHE2nPDM,4731
+mkdocs_apidescribed/parsers.py,sha256=nDHJ7mGECyeLFIOm8dcv6iPDId2AIgbeMbsTgLM_ag4,6429
+mkdocs_apidescribed/plugin.py,sha256=cxlukYTLJnAikD_TiucINExyR6sbHJTwzUYPFGLTjFo,157
+mkdocs_apidescribed/probe.py,sha256=zyXG4HPVeu5mLqcAJerfXCKeU9c8kbB_GOytUJ8A6Xo,3399
+mkdocs_apidescribed_plugin-0.1.0.dist-info/METADATA,sha256=y4qH55fOn8SBCRpq28Uj8wUqLqwGz_F-WHsj7QaQVzM,1566
+mkdocs_apidescribed_plugin-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mkdocs_apidescribed_plugin-0.1.0.dist-info/entry_points.txt,sha256=xVopkdzEjXeUcUbhsbz9KB1uP2cy2A34H4w437cwXWs,78
+mkdocs_apidescribed_plugin-0.1.0.dist-info/licenses/LICENSE,sha256=Mjp1Mmud42bwXWclwd8Rg-RZokGySkTc_Kt9yEeetr4,1514
+mkdocs_apidescribed_plugin-0.1.0.dist-info/RECORD,,

mkdocs_apidescribed_plugin-0.1.0.dist-info/WHEEL

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

mkdocs_apidescribed_plugin-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[mkdocs.plugins]
+apidescribed = mkdocs_apidescribed.plugin:ApiDescribedPlugin

mkdocs_apidescribed_plugin-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+Copyright (c) 2025, Igor `idle sign` Starikov
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the mkdocs-apidescribed-plugin nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+