diff --git a/docs/css/extra.css b/docs/css/extra.css index 3dce20dd..3a015280 100644 --- a/docs/css/extra.css +++ b/docs/css/extra.css @@ -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; diff --git a/mkdocs.yml b/mkdocs.yml index ea7a3ab2..7b5e587c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -64,6 +64,7 @@ plugins: handlers: python: options: + docstring_section_style: list show_root_toc_entry: false show_source: false diff --git a/mkdocs/plugins.py b/mkdocs/plugins.py index d5a37363..f66c6021 100644 --- a/mkdocs/plugins.py +++ b/mkdocs/plugins.py @@ -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.