Showcase¶

Let's document module mkdocs_apidescribed.probe.

 ::: apidescribed: mkdocs_apidescribed.probe
     debug: true
     ignore:
         - "_*"
         - "*ignore*"

Below is an automated documentation sample.

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.

Attributes¶

CONSTANT¶

CONSTANT: int = 1

Constant description.

ENVIRON¶

ENVIRON = environ

Alias description.

Functions¶

myfunc_google¶

myfunc_google(
    q: str,  # (1)!
    w: int,  # (2)!
    e: list,  # (3)!
    **kwargs
) -> bool

Param q
Param w
Param e

Function description.

Uses Google markup for signature description.

Note: Some note for you.

AttributeError Can raise this in some cases.

ValueError If something.

True if successful, False otherwise. Even more text for return description.

myfunc_rst¶

myfunc_rst(
    a: list[str],  # (1)!
    b: int = 0,  # (2)!
    *args,  # (3)!
    another: str,  # (4)!
    **kwargs,  # (5)!
) -> bool

comment for a
hint for b Several lines.

Warning

Some warning

Another line. https://github.com/idlesign/mkdocs-apidescribed-plugin
info for args
text for another
description for kwargs

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.

cd ~
touch this/

ValueError If something happens

KeyError If something other happens

This is returned

This is also returned

Classes¶

MyBaseClass¶

MyBaseClass(in_a: int)

Base class description.

base_attr¶

.base_attr: str = "base_attr value"

Base attr description.

prop_a ¶

.prop_a()

Property A.

method_a¶

.method_a(a=1)

Base method_a description.

method_cl ¶

.method_cl(arg1: str)

Class method.

method_st ¶

.method_st(val)

Static method.

MySubClass¶

MySubClass(in_a: int)

MyBaseClass list

Sub class description.

base_attr ¶

.base_attr: str = "base_attr value"

Base attr description.

prop_a ¶

.prop_a()

Property A.

sub_attr¶

.sub_attr = "sub_attr value"

Sub attr description.

method_a ¶

.method_a(a=1)

Base method_a description.

method_cl ¶

.method_cl(arg1: str)

Class method.

method_st ¶

.method_st(val)

Static method.

method_sub_b¶

.method_sub_b(a: str, b: int, d: float) -> str

Sub method_sub_b description.

Error example¶

Now let's try to document an unknown module somepackage.somemodule, using debug: true option for troubleshooting:

 ::: apidescribed: somepackage.somemodule
     debug: true

Automated documentation error: ImportError

Configuration

somepackage.somemodule
    debug: true

Error

With sys.path = ['/home/docs/checkouts/readthedocs.org/user_builds/mkdocs-apidescribed-plugin/checkouts/latest', '/home/docs/.asdf/installs/python/3.13.3/lib/python313.zip', '/home/docs/.asdf/installs/python/3.13.3/lib/python3.13', '/home/docs/.asdf/installs/python/3.13.3/lib/python3.13/lib-dynload', '/home/docs/checkouts/readthedocs.org/user_builds/mkdocs-apidescribed-plugin/envs/latest/lib/python3.13/site-packages'], accessing 'somepackage' raises ModuleNotFoundError: No module named 'somepackage'

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/mkdocs-apidescribed-plugin/envs/latest/lib/python3.13/site-packages/_griffe/loader.py", line 138, in load
    obj_path, package = self.finder.find_spec(
                        ~~~~~~~~~~~~~~~~~~~~~^
        objspec,  # type: ignore[arg-type]
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        try_relative_path=try_relative_path,
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        find_stubs_package=find_stubs_package,
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mkdocs-apidescribed-plugin/envs/latest/lib/python3.13/site-packages/_griffe/finder.py", line 202, in find_spec
    return module_name, self.find_package(top_module_name)
                        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mkdocs-apidescribed-plugin/envs/latest/lib/python3.13/site-packages/_griffe/finder.py", line 274, in find_package
    raise ModuleNotFoundError(module_name)
ModuleNotFoundError: somepackage

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/mkdocs-apidescribed-plugin/envs/latest/lib/python3.13/site-packages/mkdocs_apidescribed/extension.py", line 87, in run
    to_add = process_instruction(target=target, config=config)
  File "/home/docs/checkouts/readthedocs.org/user_builds/mkdocs-apidescribed-plugin/envs/latest/lib/python3.13/site-packages/mkdocs_apidescribed/extension.py", line 26, in process_instruction
    root, symbols = inspect(
                    ~~~~~~~^
        target,
        ^^^^^^^
    ...<3 lines>...
        inherited=config['inherited'],
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mkdocs-apidescribed-plugin/envs/latest/lib/python3.13/site-packages/mkdocs_apidescribed/inspector.py", line 208, in inspect
    obj = griffe.load(target)
  File "/home/docs/checkouts/readthedocs.org/user_builds/mkdocs-apidescribed-plugin/envs/latest/lib/python3.13/site-packages/_griffe/loader.py", line 809, in load
    result = loader.load(
        objspec,
    ...<2 lines>...
        find_stubs_package=find_stubs_package,
    )
  File "/home/docs/checkouts/readthedocs.org/user_builds/mkdocs-apidescribed-plugin/envs/latest/lib/python3.13/site-packages/_griffe/loader.py", line 154, in load
    top_module_object = dynamic_import(top_module_name, self.finder.search_paths)
  File "/home/docs/checkouts/readthedocs.org/user_builds/mkdocs-apidescribed-plugin/envs/latest/lib/python3.13/site-packages/_griffe/importer.py", line 107, in dynamic_import
    raise ImportError("; ".join(errors))
ImportError: With sys.path = ['/home/docs/checkouts/readthedocs.org/user_builds/mkdocs-apidescribed-plugin/checkouts/latest', '/home/docs/.asdf/installs/python/3.13.3/lib/python313.zip', '/home/docs/.asdf/installs/python/3.13.3/lib/python3.13', '/home/docs/.asdf/installs/python/3.13.3/lib/python3.13/lib-dynload', '/home/docs/checkouts/readthedocs.org/user_builds/mkdocs-apidescribed-plugin/envs/latest/lib/python3.13/site-packages'], accessing 'somepackage' raises ModuleNotFoundError: No module named 'somepackage'