mkdocs-apidescribed-plugin 0.1.0__tar.gz → 0.2.0__tar.gz

mkdocs_apidescribed_plugin-0.2.0/.github/workflows/python-package.yml

@@ -0,0 +1,33 @@
+name: Python package
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+  workflow_dispatch:
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", 3.11, 3.12]
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install deps
+      run: |
+        python -m pip install pytest coverage coveralls mkdocs-material
+    - name: Run tests
+      env:
+        GITHUB_TOKEN: ${{ secrets.github_token }}
+      run: |
+        coverage run --source=src/mkdocs_apidescribed -m pytest
+        coveralls --service=github

mkdocs_apidescribed_plugin-0.2.0/CHANGELOG

@@ -0,0 +1,15 @@
+mkdocs-apidescribed-plugin changelog
+====================================
+
+
+v0.2.0 [2025-05-11]
+-------------------
++ Add 'inherited' filter option.
++ Show class bases.
+* Fix autolinks behaviour.
+* Fix more >7th level headings.
+
+
+v0.1.0 [2025-05-09]
+-------------------
++ Basic functionality.

{mkdocs_apidescribed_plugin-0.1.0 → mkdocs_apidescribed_plugin-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-apidescribed-plugin
-Version: 0.1.0
+Version: 0.2.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-0.1.0 → mkdocs_apidescribed_plugin-0.2.0}/docs/index.md

@@ -35,12 +35,12 @@ pip install mkdocs-apidescribed-plugin
     markdown_extensions:
       - mkdocs_apidescribed.extension # this is our extention
       - admonition  # nice admonitions
-      - pymdownx.superfences
-      - pymdownx.details  # collapsible blocks
       - md_in_html  # for proper indentation
+      - pymdownx.details  # collapsible blocks
       - pymdownx.emoji:  # for icons
-        emoji_index: !!python/name:material.extensions.emoji.twemoji
-        emoji_generator: !!python/name:material.extensions.emoji.to_svg
+          emoji_index: !!python/name:material.extensions.emoji.twemoji
+          emoji_generator: !!python/name:material.extensions.emoji.to_svg
+      - pymdownx.superfences
    
     ```
 

{mkdocs_apidescribed_plugin-0.1.0 → mkdocs_apidescribed_plugin-0.2.0}/docs/showcase.md

@@ -9,7 +9,7 @@ Let's document module ``mkdocs_apidescribed.probe``.
          - "_*"
          - "*ignore*"
 ```
-**Below is automated documentation below.**
+**Below is an automated documentation sample.**
 
 ----
 

{mkdocs_apidescribed_plugin-0.1.0 → mkdocs_apidescribed_plugin-0.2.0}/mkdocs.yml

@@ -21,6 +21,7 @@ theme:
   features:
     - navigation.top
     - toc.follow
+    - content.action.view
     - content.action.edit
     - content.code.copy
     - content.code.annotate
@@ -28,6 +29,12 @@ theme:
 markdown_extensions:
   - mkdocs_apidescribed.extension
   - admonition
+  - attr_list
+  - md_in_html
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
   - pymdownx.highlight:
       anchor_linenums: true
       line_spans: __span
@@ -35,9 +42,5 @@ markdown_extensions:
   - pymdownx.inlinehilite
   - pymdownx.snippets
   - pymdownx.superfences
-  - pymdownx.details
-  - attr_list
-  - md_in_html
-  - pymdownx.emoji:
-      emoji_index: !!python/name:material.extensions.emoji.twemoji
-      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - toc:
+      permalink: true

mkdocs_apidescribed_plugin-0.2.0/src/mkdocs_apidescribed/__init__.py

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

{mkdocs_apidescribed_plugin-0.1.0 → mkdocs_apidescribed_plugin-0.2.0}/src/mkdocs_apidescribed/config.py

@@ -26,14 +26,16 @@ DEFAULT_CONFIG = {
         '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
+        'classmethod': ':material-alpha-c-box-outline:',  # for class methods
+        'staticmethod': ':material-alpha-s-box-outline:',  # for static methods
         'inherited': ':material-subdirectory-arrow-left:',  # for class inherited items
+        'clsbases': ':material-alpha-b-box:',  # for base classes
         '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
+    'inherited': True,  # describe inherited items (e.g. from parent classes)
     'types': [
         # symbol types to describe (order respected)
         'attributes',

{mkdocs_apidescribed_plugin-0.1.0 → mkdocs_apidescribed_plugin-0.2.0}/src/mkdocs_apidescribed/extension.py

@@ -23,7 +23,13 @@ class ApidescribedProcessor(Preprocessor):
         out = []
         last_type = ''
 
-        root, symbols = inspect(target, types=config['types'], ignore=config['ignore'], only=config['only'])
+        root, symbols = inspect(
+            target,
+            types=config['types'],
+            ignore=config['ignore'],
+            only=config['only'],
+            inherited=config['inherited'],
+        )
         formatter = cls_fmt(symbol=root, config=config)
 
         if prolog := formatter.run():

{mkdocs_apidescribed_plugin-0.1.0 → mkdocs_apidescribed_plugin-0.2.0}/src/mkdocs_apidescribed/formatter.py

@@ -12,9 +12,10 @@ 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()@:%-_+.~#?&/=]*)'
+    r'https?://(www\.)?[A-z0-9@:%.\-_+~#=]{1,256}\.[A-z0-9()]{1,6}\b([A-z0-9()@:%\-_+.~#?&/=]*)'
 )
 
+# todo link to src in repo
 
 class Formatter:
 
@@ -22,13 +23,14 @@ class Formatter:
         SymbolType.attr: 'Attributes',
         SymbolType.func: 'Functions',
         SymbolType.cls: 'Classes',
+        SymbolType.module: 'Modules',
     }
 
     @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'
+            return f'    ```\n{indent(val, prefix="    ")}\n    ```\n'
 
         lines = [
             f'??? failure "Automated documentation error: {exc.__class__.__name__}"',
@@ -217,12 +219,17 @@ class Formatter:
 
     def format_description(self) -> str:
         docstring = self.docstr
+        symbol = self.symbol
+        icons = self.config['icons']
 
         text = docstring.text
 
-        text = f'{text}\n'
+        prefix = ''
+        if symbol.type == SymbolType.cls:
+            if bases := [f'[``{base.name}``](#{base.name.lower()})' for base in symbol.raw.bases]:
+                prefix = f'{icons["clsbases"]} {" ".join(bases)}\n\n'
 
-        icons = self.config['icons']
+        text = f'{prefix}{text}\n'
 
         if raised := docstring.raises:
             raises = '\n\n'.join(
@@ -259,10 +266,8 @@ class Formatter:
         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'
-        )
+        heading_marker = f'{"#" * (self.heading_level + symbol.depth)} '[:7]  # 7th level max
+        title = f'{heading_marker}{icon_before} {symbol.name} {" ".join(icons_after)}\n'
 
         return title
 

{mkdocs_apidescribed_plugin-0.1.0 → mkdocs_apidescribed_plugin-0.2.0}/src/mkdocs_apidescribed/inspector.py

@@ -71,6 +71,7 @@ def get_symbol(
     undocumented: bool = False,
     ignore: list[str] = None,
     only: set[str] = None,
+    inherited: bool = True,
     depth: int = 0,
 ) -> tuple[Symbol, list[Symbol]] | None:
 
@@ -101,6 +102,7 @@ def get_symbol(
             undocumented=undocumented,
             ignore=ignore,
             only=only,
+            inherited=inherited,
             depth=depth + 1
         )
 
@@ -132,7 +134,8 @@ def get_symbols(
     undocumented: bool = False,
     ignore: list[str] = None,
     only: set[str] = None,
-    depth: int = 0
+    inherited: bool = True,
+    depth: int = 0,
 ) -> list[Symbol]:
 
     symbols = []
@@ -153,6 +156,9 @@ def get_symbols(
             docstring = symbol_raw.docstring
             skip = False
 
+            if not inherited and symbol_raw.inherited:
+                continue
+
             if docstring is None and not undocumented:
                 continue
 
@@ -174,6 +180,7 @@ def get_symbols(
                 undocumented=undocumented,
                 ignore=ignore,
                 only=only,
+                inherited=inherited,
                 depth=depth,
             )
 
@@ -193,13 +200,21 @@ def inspect(
         types: list[str],
         undocumented: bool = False,
         ignore: list[str],
-        only: list[str]
+        only: list[str],
+        inherited: bool,
 ) -> 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))
+    symbols = get_symbols(
+        obj,
+        types=types,
+        undocumented=undocumented,
+        ignore=ignore,
+        only=set(only),
+        inherited=inherited,
+    )
 
     return root, symbols

{mkdocs_apidescribed_plugin-0.1.0 → mkdocs_apidescribed_plugin-0.2.0}/src/mkdocs_apidescribed/probe.py

@@ -157,7 +157,7 @@ class MyBaseClass:
         return True
 
 
-class MySubClass(MyBaseClass):
+class MySubClass(MyBaseClass, list):
     """Sub class description."""
 
     sub_attr = "sub_attr value"

mkdocs_apidescribed_plugin-0.1.0/CHANGELOG

@@ -1,8 +0,0 @@
-mkdocs-apidescribed-plugin changelog
-=================================
-
-
-Unreleased
-----------
-+ Basic functionality.
-

mkdocs_apidescribed_plugin-0.1.0/src/mkdocs_apidescribed/__init__.py

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