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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-apidescribed-plugin
-Version: 0.1.0
+Version: 1.0.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.0/mkdocs_apidescribed/__init__.py

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

{mkdocs_apidescribed_plugin-0.1.0/src → mkdocs_apidescribed_plugin-1.0.0}/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/src → mkdocs_apidescribed_plugin-1.0.0}/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/src → mkdocs_apidescribed_plugin-1.0.0}/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/src → mkdocs_apidescribed_plugin-1.0.0}/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/src → mkdocs_apidescribed_plugin-1.0.0}/mkdocs_apidescribed/probe.py

@@ -20,7 +20,7 @@ ENVIRON = environ
 """Alias description."""
 
 
-def undocumented():
+def undocumented():  # pragma: nocover
     pass
 
 
@@ -152,12 +152,12 @@ class MyBaseClass:
     def __str__(self):
         """Specialized. To string."""
 
-    def method_a(self, a=1):
+    def method_a(self, a=1):  # pragma: nocover
         """Base method_a description."""
         return True
 
 
-class MySubClass(MyBaseClass):
+class MySubClass(MyBaseClass, list):
     """Sub class description."""
 
     sub_attr = "sub_attr value"
@@ -169,6 +169,6 @@ class MySubClass(MyBaseClass):
         a: str,
         b: int,
         d: float,
-    ) -> str:
+    ) -> str:  # pragma: nocover
         """Sub method_sub_b description."""
         return ''

{mkdocs_apidescribed_plugin-0.1.0 → mkdocs_apidescribed_plugin-1.0.0}/pyproject.toml

@@ -25,11 +25,24 @@ Documentation = "https://mkdocs-apidescribed-plugin.readthedocs.org/"
 
 [dependency-groups]
 dev = [
+    {include-group = "docs"},
+    {include-group = "linters"},
+    {include-group = "tests"},
+]
+docs = [
     "mkdocs",
     "mkdocs-material",
-    "pytest",
+]
+linters = [
     "ruff",
 ]
+tests = [
+    "pytest",
+    "pytest-cov",
+    "pytest-datafixtures",
+    "coverage",
+]
+
 
 [build-system]
 requires = ["hatchling"]
@@ -40,3 +53,19 @@ path = "src/mkdocs_apidescribed/__init__.py"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/mkdocs_apidescribed"]
+
+[tool.hatch.build.targets.sdist]
+packages = ["src/mkdocs_apidescribed"]
+
+[tool.coverage.run]
+source = [
+    "src/",
+]
+omit = []
+
+[tool.coverage.report]
+fail_under = 98.00
+exclude_also = [
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+]

mkdocs_apidescribed_plugin-0.1.0/.coveragerc

@@ -1,3 +0,0 @@
-[run]
-source = src/
-

mkdocs_apidescribed_plugin-0.1.0/.readthedocs.yaml

@@ -1,12 +0,0 @@
-version: 2
-
-build:
-  os: "ubuntu-24.04"
-  tools:
-    python: "3"
-  jobs:
-    pre_install:
-      - pip install mkdocs-material mkdocs-apidescribed-plugin
-
-mkdocs:
-  configuration: mkdocs.yml

mkdocs_apidescribed_plugin-0.1.0/AUTHORS

@@ -1,18 +0,0 @@
-mkdocs-apidescribed-plugin authors
-===============================
-
-Created by Igor `idle sign` Starikov.
-
-
-Contributors
-------------
-
-Here could be your name.
-
-
-
-Translators
------------
-
-Here could be your name.
-

mkdocs_apidescribed_plugin-0.1.0/CHANGELOG

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

mkdocs_apidescribed_plugin-0.1.0/CONTRIBUTING

@@ -1,25 +0,0 @@
-mkdocs-apidescribed-plugin contributing
-====================================
-
-
-Submit issues
--------------
-
-If you spotted something weird in application behavior or want to propose a feature you are welcome.
-
-
-Write code
-----------
-If you are eager to participate in application development and to work on an existing issue (whether it should
-be a bugfix or a feature implementation), fork, write code, and make a pull request right from the forked project page.
-
-
-Spread the word
----------------
-
-If you have some tips and tricks or any other words that you think might be of interest for the others — publish it
-wherever you find convenient.
-
-
-See also: https://github.com/idlesign/mkdocs-apidescribed-plugin
-

mkdocs_apidescribed_plugin-0.1.0/INSTALL

@@ -1,27 +0,0 @@
-mkdocs-apidescribed-plugin installation
-====================================
-
-
-Python ``pip`` package is required to install ``mkdocs-apidescribed-plugin``.
-
-
-From sources
-------------
-
-Use the following command line to install ``mkdocs-apidescribed-plugin`` from sources directory (containing setup.py):
-
-    pip install .
-
-
-From PyPI
----------
-
-Alternatively you can install ``mkdocs-apidescribed-plugin`` from PyPI:
-
-    pip install mkdocs-apidescribed-plugin
-
-
-Use `-U` flag for upgrade:
-
-    pip install -U mkdocs-apidescribed-plugin
-

mkdocs_apidescribed_plugin-0.1.0/docs/config.md

@@ -1,25 +0,0 @@
-# Configuration
-
-To configure ``apidescribed`` one can use yaml just after  ``::: apidescribed: `` directive:
-
-```
- ::: apidescribed: mkdocs_apidescribed.config
-     debug: true
-     categorize: false
-     only: 
-         - DEFAULT_CONFIG
-     location:
-         mode: module
-```
-
-----
-
-**All available configuration options are listed below:**
-
-::: apidescribed: mkdocs_apidescribed.config
-    debug: true
-    categorize: false
-    only: 
-        - DEFAULT_CONFIG
-    location:
-        mode: module

mkdocs_apidescribed_plugin-0.1.0/docs/index.md

@@ -1,71 +0,0 @@
-# Introduction
-
-*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
-
-!!! tip
-    See demo in ``Showcase`` section.
-
-## Requirements
-
-1.  Python 3.10+
-2.  `mkdocs` package
-
-## Installation
-
-``` shell
-pip install mkdocs-apidescribed-plugin
-```
-
-## Configuration
-
-1. Add ``apidescribed`` into ``mkdocs.yml``:
-
-    ```yaml title="mkdocs.yml"
-    theme:
-      ...
-      features:
-        ...
-        - content.code.annotate  # for parameter descriptions
-   
-    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.emoji:  # for icons
-        emoji_index: !!python/name:material.extensions.emoji.twemoji
-        emoji_generator: !!python/name:material.extensions.emoji.to_svg
-   
-    ```
-
-2. Add ``::: apidescribed:`` directive into your documentation followed by a module path:
-
-    ```md title="index.md"
-    This is my documentation
-   
-    ::: apidescribed: somepackage.somemodule
-   
-    ```
-
-
-## Get involved into mkdocs-apidescribed
-
-!!! success "Submit issues"
-    If you spotted something weird in application behavior or want to propose a feature you can do 
-    that at <https://github.com/idlesign/mkdocs-apidescribed-plugin/issues>
-
-!!! tip "Write code"
-    If you are eager to participate in application development, 
-    fork it at <https://github.com/idlesign/mkdocs-apidescribed-plugin>, write 
-    your code, whether it should be a bugfix or a feature implementation,
-    and make a pull request right from the forked project page.
-
-!!! info "Spread the word"
-    If you have some tips and tricks or any other words in mind that 
-    you think might be of interest for the others --- publish it.

mkdocs_apidescribed_plugin-0.1.0/docs/showcase.md

@@ -1,33 +0,0 @@
-# Showcase
-
-Let's document module ``mkdocs_apidescribed.probe``.
-
-```
- ::: apidescribed: mkdocs_apidescribed.probe
-     debug: true
-     ignore:
-         - "_*"
-         - "*ignore*"
-```
-**Below is automated documentation below.**
-
-----
-
-::: apidescribed: mkdocs_apidescribed.probe
-    debug: true
-    ignore:
-        - "_*"
-        - "*ignore*"
-
-## Error example
-
-Now let's try to document an unknown module ``somepackage.somemodule``,
-using ``debug: true`` option for troubleshooting:
-
-```
- ::: apidescribed: somepackage.somemodule
-     debug: true
-```
-
-::: apidescribed: somepackage.somemodule
-    debug: true

mkdocs_apidescribed_plugin-0.1.0/mkdocs.yml

@@ -1,43 +0,0 @@
-site_name: mkdocs-apidescribed
-site_url: !ENV READTHEDOCS_CANONICAL_URL
-
-copyright: Copyright © 2025, Igor Starikov
-
-repo_url: https://github.com/idlesign/mkdocs-apidescribed-plugin
-edit_uri: edit/master/docs/
-
-extra:
-  social:
-    - icon: fontawesome/brands/github
-      link: https://github.com/idlesign
-
-plugins:
-  - search
-
-theme:
-  name: material
-  palette:
-    primary: green
-  features:
-    - navigation.top
-    - toc.follow
-    - content.action.edit
-    - content.code.copy
-    - content.code.annotate
-
-markdown_extensions:
-  - mkdocs_apidescribed.extension
-  - admonition
-  - pymdownx.highlight:
-      anchor_linenums: true
-      line_spans: __span
-      pygments_lang_class: true
-  - 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

mkdocs_apidescribed_plugin-0.1.0/src/mkdocs_apidescribed/__init__.py

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

mkdocs_apidescribed_plugin-0.1.0/tests/test_module.py

@@ -1,3 +0,0 @@
-
-def test_me():
-    assert True

mkdocs_apidescribed_plugin-0.1.0/tools/buildme.py

@@ -1,13 +0,0 @@
-import os
-
-from mkdocs.commands import build
-from mkdocs import config
-
-os.chdir('../')
-
-cfg = config.load_config()
-cfg.plugins.on_startup(command='build', dirty=False)
-try:
-    build.build(cfg)
-finally:
-    cfg.plugins.on_shutdown()