mkdocs-apidescribed-plugin 0.1.0__tar.gz

mkdocs_apidescribed_plugin-0.1.0/.coveragerc

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

mkdocs_apidescribed_plugin-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.project
+.pydevproject
+.idea
+.tox
+__pycache__
+*.env
+*.pyc
+*.pyo
+*.egg-info
+docs/_build/
+

mkdocs_apidescribed_plugin-0.1.0/.readthedocs.yaml

@@ -0,0 +1,12 @@
+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

@@ -0,0 +1,18 @@
+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

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

mkdocs_apidescribed_plugin-0.1.0/CONTRIBUTING

@@ -0,0 +1,25 @@
+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

@@ -0,0 +1,27 @@
+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/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.
+

mkdocs_apidescribed_plugin-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,29 @@
+# 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/docs/config.md

@@ -0,0 +1,25 @@
+# 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

@@ -0,0 +1,71 @@
+# 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

@@ -0,0 +1,33 @@
+# 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

@@ -0,0 +1,43 @@
+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/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "mkdocs-apidescribed-plugin"
+dynamic = ["version"]
+description = "mkdocs plugin to generate API documentation for Python programs"
+authors = [
+    { name = "Igor Starikov", email = "idlesign@yandex.ru" }
+]
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+keywords = ["mkdocs", "api", "plugin"]
+dependencies = [
+    "mkdocs",
+    "griffe",
+    "PyYAML",
+]
+
+[project.urls]
+Homepage = "https://github.com/idlesign/mkdocs-apidescribed-plugin"
+Documentation = "https://mkdocs-apidescribed-plugin.readthedocs.org/"
+
+[project.entry-points."mkdocs.plugins"]
+"apidescribed" = "mkdocs_apidescribed.plugin:ApiDescribedPlugin"
+
+[dependency-groups]
+dev = [
+    "mkdocs",
+    "mkdocs-material",
+    "pytest",
+    "ruff",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/mkdocs_apidescribed/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mkdocs_apidescribed"]

mkdocs_apidescribed_plugin-0.1.0/src/mkdocs_apidescribed/__init__.py

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

mkdocs_apidescribed_plugin-0.1.0/src/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_plugin-0.1.0/src/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)