centersl/mkdocs
1
0
Fork 0
mirror of https://github.com/mkdocs/mkdocs.git synced 2026-03-27 09:58:31 +07:00
Code Issues Packages Projects Releases Wiki Activity

Add type annotations for plugin events, include them in the docs

Browse Source
This commit is contained in:
Oleh Prypin
2022-08-14 17:21:33 +02:00
parent f79b34d174
commit 12841f1aa5
3 changed files with 48 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/css/extra.css
View File

@@ -30,6 +30,10 @@ dd {
padding-left: 20px;
}
.doc-contents .field-body p:first-of-type {
display: inline;
}
.card-body svg {
width: 100%;
padding: 0 50px;

1
mkdocs.yml
View File

@@ -64,6 +64,7 @@ plugins:
handlers:
python:
options:
docstring_section_style: list
show_root_toc_entry: false
show_source: false

63
mkdocs/plugins.py
View File

@@ -6,10 +6,16 @@ Implements the plugin API for MkDocs.
import logging
from collections import OrderedDict
from typing import Any, Callable, Dict, List, Optional, Tuple, TypeVar
import importlib_metadata
import jinja2.environment
from mkdocs.config.base import Config
from mkdocs.livereload import LiveReloadServer
from mkdocs.structure.files import Files
from mkdocs.structure.nav import Navigation
from mkdocs.structure.pages import Page
log = logging.getLogger('mkdocs.plugins')
@@ -61,7 +67,9 @@ class BasePlugin:
config_scheme = ()
config = {}
def load_config(self, options, config_file_path=None):
def load_config(
self, options: Dict[str, Any], config_file_path: Optional[str] = None
) -> Tuple[List[str], List[str]]:
"""Load config from a dict of options. Returns a tuple of (errors, warnings)."""
self.config = Config(schema=self.config_scheme, config_file_path=config_file_path)
@@ -71,7 +79,9 @@ class BasePlugin:
# Global events
def on_serve(self, server, config, builder):
def on_serve(
self, server: LiveReloadServer, config: Config, builder: Callable
) -> Optional[LiveReloadServer]:
"""
The `serve` event is only called when the `serve` command is used during
development. It is passed the `Server` instance which can be modified before
@@ -88,7 +98,7 @@ class BasePlugin:
"""
return server
def on_config(self, config):
def on_config(self, config: Config) -> Optional[Config]:
"""
The `config` event is the first event called on build and is run immediately
after the user configuration is loaded and validated. Any alterations to the
@@ -102,7 +112,7 @@ class BasePlugin:
"""
return config
def on_pre_build(self, config):
def on_pre_build(self, config: Config) -> None:
"""
The `pre_build` event does not alter any variables. Use this event to call
pre-build scripts.
@@ -111,7 +121,7 @@ class BasePlugin:
config: global configuration object
"""
def on_files(self, files, config):
def on_files(self, files: Files, config: Config) -> Optional[Files]:
"""
The `files` event is called after the files collection is populated from the
`docs_dir`. Use this event to add, remove, or alter files in the
@@ -128,7 +138,7 @@ class BasePlugin:
"""
return files
def on_nav(self, nav, config, files):
def on_nav(self, nav: Navigation, config: Config, files: Files) -> Optional[Navigation]:
"""
The `nav` event is called after the site navigation is created and can
be used to alter the site navigation.
@@ -143,7 +153,9 @@ class BasePlugin:
"""
return nav
def on_env(self, env, config, files):
def on_env(
self, env: jinja2.Environment, config: Config, files: Files
) -> Optional[jinja2.Environment]:
"""
The `env` event is called after the Jinja template environment is created
and can be used to alter the
@@ -159,7 +171,7 @@ class BasePlugin:
"""
return env
def on_post_build(self, config):
def on_post_build(self, config: Config) -> None:
"""
The `post_build` event does not alter any variables. Use this event to call
post-build scripts.
@@ -168,7 +180,7 @@ class BasePlugin:
config: global configuration object
"""
def on_build_error(self, error):
def on_build_error(self, error: Exception) -> None:
"""
The `build_error` event is called after an exception of any kind
is caught by MkDocs during the build process.
@@ -182,7 +194,9 @@ class BasePlugin:
# Template events
def on_pre_template(self, template, template_name, config):
def on_pre_template(
self, template: jinja2.Template, template_name: str, config: Config
) -> Optional[jinja2.Template]:
"""
The `pre_template` event is called immediately after the subject template is
loaded and can be used to alter the template.
@@ -197,7 +211,9 @@ class BasePlugin:
"""
return template
def on_template_context(self, context, template_name, config):
def on_template_context(
self, context: Dict[str, Any], template_name: str, config: Config
) -> Optional[Dict[str, Any]]:
"""
The `template_context` event is called immediately after the context is created
for the subject template and can be used to alter the context for that specific
@@ -213,7 +229,7 @@ class BasePlugin:
"""
return context
def on_post_template(self, output_content, template_name, config):
def on_post_template(self, output_content: str, template_name: str, config: Config) -> str:
"""
The `post_template` event is called after the template is rendered, but before
it is written to disc and can be used to alter the output of the template.
@@ -232,7 +248,7 @@ class BasePlugin:
# Page events
def on_pre_page(self, page, config, files):
def on_pre_page(self, page: Page, config: Config, files: Files) -> Optional[Page]:
"""
The `pre_page` event is called before any actions are taken on the subject
page and can be used to alter the `Page` instance.
@@ -247,7 +263,7 @@ class BasePlugin:
"""
return page
def on_page_read_source(self, page, config):
def on_page_read_source(self, page: Page, config: Config) -> Optional[str]:
"""
The `on_page_read_source` event can replace the default mechanism to read
the contents of a page's source from the filesystem.
@@ -262,7 +278,9 @@ class BasePlugin:
"""
return None
def on_page_markdown(self, markdown, page, config, files):
def on_page_markdown(
self, markdown: str, page: Page, config: Config, files: Files
) -> Optional[str]:
"""
The `page_markdown` event is called after the page's markdown is loaded
from file and can be used to alter the Markdown source text. The meta-
@@ -279,7 +297,7 @@ class BasePlugin:
"""
return markdown
def on_page_content(self, html, page, config, files):
def on_page_content(self, html: str, page: Page, config: Config, files: Files) -> Optional[str]:
"""
The `page_content` event is called after the Markdown text is rendered to
HTML (but before being passed to a template) and can be used to alter the
@@ -296,7 +314,9 @@ class BasePlugin:
"""
return html
def on_page_context(self, context, page, config, nav):
def on_page_context(
self, context: Dict[str, Any], page: Page, config: Config, nav: Navigation
) -> Optional[Dict[str, Any]]:
"""
The `page_context` event is called after the context for a page is created
and can be used to alter the context for that specific page only.
@@ -312,7 +332,7 @@ class BasePlugin:
"""
return context
def on_post_page(self, output, page, config):
def on_post_page(self, output: str, page: Page, config: Config) -> str:
"""
The `post_page` event is called after the template is rendered, but
before it is written to disc and can be used to alter the output of the
@@ -330,6 +350,9 @@ class BasePlugin:
return output
T = TypeVar('T')
class PluginCollection(OrderedDict):
"""
A collection of plugins.
@@ -342,7 +365,7 @@ class PluginCollection(OrderedDict):
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
def __setitem__(self, key, value, **kwargs):
def __setitem__(self, key: str, value: BasePlugin, **kwargs):
if not isinstance(value, BasePlugin):
raise TypeError(
f'{self.__module__}.{self.__name__} only accepts values which'
@@ -351,7 +374,7 @@ class PluginCollection(OrderedDict):
)
super().__setitem__(key, value, **kwargs)
def run_event(self, name, item=None, **kwargs):
def run_event(self, name: str, item: T = None, **kwargs) -> T:
"""
Run all registered methods of an event.