Metadata-Version: 2.1
Name: docums-simple-hooks
Version: 0.1.5
Summary: Define your own hooks for docums, without having to create a new package.
Home-page: https://github.com/khanhduy1407/docums-simple-hooks
Author: NKDuy
Author-email: kn145660@gmail.com
License: MIT
Description: # docums-simple-hooks
        
        Define your own hooks for docums, without having to create a new package.
        
        ## Setup
        
        Install the plugin using pip:
        
        ```bash
        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`:
        
        ```yaml
        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][docums-plugins].
        
        ## 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][docums-hooks].
        
        ## 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:  
        
        ```python
        import shutil
        
        def copy_readme(*args, **kwargs):
            shutil.copy("README.md", "docs/index.md")
        ```
        
        Now, register the hook in your `docums.yml`:  
        
        ```yaml
        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](https://khanhduy1407.github.io/docums/user-guide/configuration/#environment-variables)). Example:
        
        ```yaml
        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:
        
        ```bash
        export ENABLE_DOCUMS_SIMPLE_HOOKS=false
        docums serve
        ```
        
        [docums-plugins]: http://khanhduy1407.github.io/docums/user-guide/plugins/
        [docums-hooks]: https://khanhduy1407.github.io/docums/user-guide/plugins/#events
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Documentation
Description-Content-Type: text/markdown
Provides-Extra: test
