docums-simple-hooks 0.1.5

Define your own hooks for docums, without having to create a new package.

docums-simple-hooks

Define your own hooks for docums, without having to create a new package.

Setup

Install the plugin using pip:

pip install docums-simple-hooks

Next, add a python module to either the docs/ directory or the root docums directory. Then, add the plugin and hooks definition to your docums.yml:

plugins:
  - search
  - docums-simple-hooks:
      hooks:
        hook-name: "your.module:hook_function"

If you have no plugins entry in your config file yet, you'll likely also want to add the search plugin. Docums enables it by default if there is no plugins entry set.

More information about plugins in the Docums documentation.

Usage

You can use this plugin to create simple hooks for docums without having to create a separate plugin package.

Just define a function and register it as a hook in the docums.yml. The function shall have the same API as the desired hook. To see available hooks and their API, see the events chapter in the docums documentation.

Example

Let's say you want to copy the README.md file to docs/index.md. To do that, create a new file, e.g.: docs/hooks.py, and put the following function there:

import shutil

def copy_readme(*args, **kwargs):
    shutil.copy("README.md", "docs/index.md")

Now, register the hook in your docums.yml:

plugins:
  - docums-simple-hooks:
      hooks:
        on_pre_build: "docs.hooks:copy_readme"

That's all - the copy_readme() function will run every time, before building the documentation.

Disabling the plugin

You can use the enabled option to optionally disable this plugin. A possible use case is local development where you might want faster build times. It's recommended to use this option with an environment variable together with a default fallback (introduced in docums v1.2.0, see docs). Example:

plugins:
  - docums-simple-hooks:
      enabled: !ENV [ENABLE_DOCUMS_SIMPLE_HOOKS, True]
      hooks:
        on_pre_build: "docs.hooks:copy_readme"

Which enables you to disable the plugin locally using:

export ENABLE_DOCUMS_SIMPLE_HOOKS=false
docums serve