From 1c80f6d6637cc4e471bc3f96c056e1d30e02b2bc Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Fri, 9 Mar 2018 16:10:29 -0500 Subject: [PATCH] Better document plugin config Fixes #1391. --- docs/user-guide/plugins.md | 37 ++++++++++++++++++++++++++++++++----- 1 file changed, 32 insertions(+), 5 deletions(-) diff --git a/docs/user-guide/plugins.md b/docs/user-guide/plugins.md index 5860096c..fbf53d3c 100644 --- a/docs/user-guide/plugins.md +++ b/docs/user-guide/plugins.md @@ -67,19 +67,46 @@ All `BasePlugin` subclasses contain the following attributes: #### config_scheme -: A tuple of configuration validation class instances (to be defined in a subclass). +: A tuple of configuration validation instances. Each item must consist of a + two item tuple in which the first item is the string name of the + configuration option and the second item is an instance of + `mkdocs.config.config_options.BaseConfigOption` or any of its subclasses. + + For example, the following `config_scheme` defines three configuration options: `foo`, which accepts a string; `bar`, which accepts an integer; and `baz`, which accepts a boolean value. + + class MyPlugin(mkdocs.plugins.BasePlugin): + config_scheme = ( + ('foo', mkdocs.config.config_options.Type(mkdocs.utils.string_types, default='a default value')), + ('bar', mkdocs.config.config_options.Type(int, default=0)), + ('baz', mkdocs.config.config_options.Type(bool, default=True)) + ) + + When the user's configuration is loaded, the above scheme will be used to + validate the configuration and fill in any defaults for settings not + provided by the user. The validation classes may be any of the classes + provided in `mkdocs.config.config_options` or a third party subclass defined + in the plugin. + + Any settings provided by the user which fail validation or are not defined + in the `config_scheme` will raise a `mkdocs.config.base.ValidationError`. #### config -: A dictionary of configuration options for the plugin which is populated by the - `load_config` method. +: A dictionary of configuration options for the plugin, which is populated by + the `load_config` method after configuration validation has completed. Use + this attribute to access options provided by the user. + + def on_pre_build(self, config): + if self.config['bool_option']: + # implement "bool_option" functionality here... All `BasePlugin` subclasses contain the following method(s): #### load_config(options) -: Loads configuration from a dictionary of options. Returns a tuple of `(errors, - warnings)`. +: Loads configuration from a dictionary of options. Returns a tuple of + `(errors, warnings)`. This method is called by MkDocs during configuration + validation and should not need to be called by the plugin. #### on_<event_name>()