Customization

Customization 'on_config'.

MkApi has an option on_config to allow users to configure MkDocs/MkApi or user system environment. Here is an example directory structure and the corresponding mkdocs.yml:

# Directory structure
myproject:
  - docs:
    - index.md
  - examples:
    - custom.py
  - mkdocs.yml
# mkdocs.yml
plugins:
  - search
  - mkapi:
      src_dirs: [examples]
      on_config: custom.on_config

Customization script is defined in examples/custom.py:

File 6 examples/custom.py

def on_config():
    # Here you can do all you want.
    print("Called.")


def on_config_with_config(config):
    print("Called with config.")
    print(config["docs_dir"])

    # You can change config, for example:
    # config['docs_dir'] = 'other_directory'

    # Optionally, you can return altered config to customize MkDocs.
    # return config


def on_config_with_mkapi(config, mkapi):
    print("Called with config and mkapi.")
    print(config["docs_dir"])
    print(mkapi)

Let's build the documentation.

$ mkdocs build
INFO    -  [MkApi] Calling user 'on_config' with []
Called.
INFO    -  Cleaning site directory
...

on_config() can take config and/or mkapi arguments.

# mkdocs.yml
plugins:
  - search
  - mkapi:
      src_dirs: [examples]
      on_config: custom.on_config_with_config
$ mkdocs build
INFO    -  [MkApi] Calling user 'on_config' with ['config']
Called with config.
C:\Users\daizu\Documents\github\mkapi\docs
INFO    -  Cleaning site directory
...
# mkdocs.yml
plugins:
  - search
  - mkapi:
      src_dirs: [examples]
      on_config: custom.on_config_with_mkapi
$ mkdocs build
INFO    -  [MkApi] Calling user 'on_config' with ['config', 'mkapi']
Called with config and mkapi.
C:\Users\daizu\Documents\github\mkapi\docs
<mkapi.plugins.mkdocs.MkapiPlugin object at 0x000001DF712D0F08>
INFO    -  Cleaning site directory
...