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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-apidescribed-plugin
-Version: 1.0.1
+Version: 1.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/

{mkdocs_apidescribed_plugin-1.0.1 → mkdocs_apidescribed_plugin-1.1.0}/pyproject.toml

@@ -55,7 +55,7 @@ path = "src/mkdocs_apidescribed/__init__.py"
 packages = ["src/mkdocs_apidescribed"]
 
 [tool.hatch.build.targets.sdist]
-packages = ["src/mkdocs_apidescribed"]
+packages = ["src/"]
 
 [tool.coverage.run]
 source = [

mkdocs_apidescribed_plugin-1.1.0/src/mkdocs_apidescribed/__init__.py

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

{mkdocs_apidescribed_plugin-1.0.1 → mkdocs_apidescribed_plugin-1.1.0/src}/mkdocs_apidescribed/inspector.py

@@ -25,7 +25,7 @@ class Symbol:
     type: SymbolType
     name: str
     source: str
-    docstr: griffe.Docstring
+    docstr: str
     path: str
     fpath: str
     params: griffe.Parameters | None
@@ -108,7 +108,7 @@ def get_symbol(
 
     if not symbol_type:
         log.error(f'Unsupported symbol type: {obj}. Skipped.')
-        return
+        return None
 
     symbol = Symbol(
         depth=depth,
@@ -116,7 +116,7 @@ def get_symbol(
         type=symbol_type,
         name=obj.name,
         source=obj.source,
-        docstr=obj.docstring,
+        docstr=getattr(obj.docstring, 'value', None) or '',
         path=obj.path,
         fpath=f'{obj.relative_package_filepath}',
         params=params,

{mkdocs_apidescribed_plugin-1.0.1 → mkdocs_apidescribed_plugin-1.1.0/src}/mkdocs_apidescribed/parsers.py

@@ -4,8 +4,6 @@ from dataclasses import dataclass, field
 from textwrap import dedent
 from typing import TYPE_CHECKING
 
-import griffe
-
 if TYPE_CHECKING:
     from .formatter import Formatter
 
@@ -25,7 +23,7 @@ class Block:
 
     def __init__(self, marker: str = '', arg: str = '', value: str = ''):
         self.marker = marker or self.unmarked
-        self.arg = arg.strip()
+        self.arg = arg.strip().partition(' ')[0]  # e.g.: "arg (int)"
         self.value = value
         self.addition = []
 
@@ -47,9 +45,9 @@ class DocstrParser:
     registry: dict[str, type['DocstrParser']] = {}
 
     @classmethod
-    def parse(cls, docstr: griffe.Docstring | None, *, config: dict, formatter: 'Formatter') -> Docstring:
+    def parse(cls, docstr: str, *, config: dict, formatter: 'Formatter') -> Docstring:
 
-        value = getattr(docstr, 'value', None) or ''
+        value = docstr
         docstring = Docstring(text=f'{value}')
 
         if value:
@@ -87,9 +85,64 @@ class DocstrParser:
     def run(self) -> Docstring | None:
         return self._parse(self.src)
 
+    def normalize(self, text: str) -> str:
+        return text
+
     def postprocess(self, text: str) -> str:
         return text
 
+    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:  # pragma: nocover
         return
 
@@ -154,76 +207,84 @@ class SphinxParser(DocstrParser):
 
         return '\n'.join(lines)
 
-    def parse_blocks(
-            self,
-            *,
-            pattern: re.Pattern,
-            value: str,
-    ) -> tuple[dict[str, list[Block]], list[Block]]:
+    def _parse(self, value: str) -> Docstring | None:
 
-        blocks: dict[str, list[Block]] = defaultdict(list)
-        block_last: Block | None = None
-        marker_detected = False
+        blocks, processed = self.parse_blocks(
+            pattern=self.re_markers,
+            value=self.normalize(value),
+        )
 
-        processed = []
+        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'
+
+    re_markers = re.compile(
+        r'^::(?P<marker>Args|Yields|Returns|Raises|Examples)::'
+        r'(?P<arg>[^:]*):\s*(?P<value>.*)'
+    )
+
+    re_preproc = re.compile(r'^(?P<marker>Args|Yields|Returns|Raises|Examples):$')
+
+    def normalize(self, value: str) -> str:
+        pattern = self.re_preproc
+        normalized = []
+        marker_stack = []
+        marker_depth = 0
 
         for line in value.splitlines():
 
             is_empty = len(line.strip()) == 0
 
-            if block_last:
+            if marker_stack:
                 if line.startswith(' ') or is_empty:
-                    # must be a continuation of a block
-                    block_last.contribute(line)
-                    continue
+                    unindented = line.lstrip(' ')
+                    indent_size = len(line) - len(unindented)
 
-                # previous block ended
-                processed.append(block_last)
-                block_last = None
+                    if not marker_depth or indent_size == marker_depth:
+                        marker_depth = indent_size
+                        marker_stack.append(f"::{marker_stack[0]}:: {unindented}")
 
-            if matched := pattern.match(line):
-                marker_detected = True
-                marker = matched.group('marker')
+                    elif indent_size > marker_depth:
+                        # deeper: block body (continuation)
+                        reindented = f'{" " * (indent_size-marker_depth)}{unindented}'
+                        marker_stack[-1] = f'{marker_stack[-1]}\n{reindented}'
+                    else:
+                        # end of block
+                        normalized.extend(marker_stack[1:])
+                        marker_stack.clear()
+                        marker_depth = 0
 
-                arg = matched.group('arg')
-                val = matched.group('value')
+                continue
 
-                block = Block(marker, arg, val.strip())
-                blocks[marker].append(block)
-                block_last = block
+            if matched := pattern.match(line):
+                marker_stack.append(matched.group('marker'))
 
             else:
-                block = Block()
-                block.contribute(line)
-                blocks[Block.unmarked].append(block)
-                processed.append(block)
+                normalized.append(line)
 
-        if block_last:
-            # block in the last line
-            processed.append(block_last)
-
-        self.markers_detected = self.markers_detected or marker_detected
-
-        return blocks, processed
+        return '\n'.join(normalized)
 
     def _parse(self, value: str) -> Docstring | None:
 
         blocks, processed = self.parse_blocks(
             pattern=self.re_markers,
-            value=value,
+            value=self.normalize(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']),
+            params=self.to_dict(blocks['Args']),
+            returns=self.to_list(blocks['Returns']),
+            raises=self.to_dict(blocks['Raises']),
         )
 
 
-class GoogleParser(DocstrParser):
-    alias: str = 'google'
-
-
 class NumpyParser(DocstrParser):
     alias: str = 'numpy'

mkdocs_apidescribed_plugin-1.0.1/mkdocs_apidescribed/__init__.py

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