aklajnert / mkdocs-simple-hooks Goto Github PK

View Code? Open in Web Editor NEW

56.0 56.0 5.0 43 KB

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

License: MIT License

Python 100.00%

mkdocs-simple-hooks's People

Stargazers

Watchers

Forkers

honzajavorek jdoiro3 timvink icodein ml719

mkdocs-simple-hooks's Issues

The module path can't be nested

Hi, thanks for this project, it's a great idea. I discovered the plugin has problems with module names like my.nested.module.name. The __import__() doesn't seem to handle it well.

I tried to replace it with importlib.import_module() and all started to work. Is there a specific reason why __import__() is used? If not, would you accept a Pull Request fixing this?

Update example use case

The example use case doesn't do justice to this plugin imho, as

embedding external files is well documented (see https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#embedding-external-files)
copying README.md into index.md creates unnecessary git diffs

pip install mkdocs-material

# mkdocs.yml
markdown_extensions:
  - pymdownx.snippets

# index.md
--8<-- "README.md"

I think this plugin really shines when you're creating assets (on_pre_build) for your documentation. I'm biased, but I like the combination with mkdocs-table-reader-plugin , mkdocs-charts-plugin and mkdocs-markdownextradata-plugin.

How about an example with a python function that downloads a random kitty image (https://docs.thecatapi.com/) ? Or the latest XKCD (https://xkcd.com/info.0.json) ? Or just saves a machine learning model performance metric into a docs/assets/metrics.json file you can insert into your site?

Happy to provide a PR if you're interested.

Push the updated README to https://pypi.org/project/mkdocs-simple-hooks/

Including #2 fix.

Invalid config option

Hi! I like the idea of your plugin but it doesn't work that way for me.

I tried your sample code and get the following error:

ERROR   -  Config value: 'plugins'. Error: Plugin value: 'hooks'. Error: Expected type: <class 'dict'> but received: <class 'list'>

My config:

# Plugins
plugins:
  - mkdocs-simple-hooks:
      hooks:
        - on_pre_build: "docs.hooks:copy_readme"

I am using the latest plugin version (0.1.1), mkdocs 1.1.2, python 3.7 64bit

If i debug into your plugin there seems to be something wrong how the hook config value is read:

[{'on_pre_build': 'docs.hooks:copy_readme'}]
> special variables
> function variables
> 0:{'on_pre_build': 'docs.hooks:copy_readme'}
> len():1

Do you know what could be wrong in my configuration? It seems that the codes workes for you?

Hooks "on_env" not working

Hello,

first of all thank you for this plugin, to extend mkdocs features without having to create a new package. 😃

I have problem about the implementation of on_env hook to add a my own jinja2 filter .

There is my mkdocs.yml configuration :

plugins:
  - mkdocs-simple-hooks:
      hooks:
        on_env: "docs.hooks:on_env"

The contents of the file docs/hooks.py

def say_hello(s:str):
    return "<i>Hello %s</i>" % s

def on_env(env, config, files, **kwargs):
    env.filters['say_hello'] = say_hello
    return env

From a jinja2 template the new filter is called like this

{{nav_item.title|say_hello}}

After running mkdocs command (mkdocs serve) I get the following error

jinja2.exceptions.TemplateAssertionError: No filter named 'say_hello'.

Complete stacktrace

INFO     -  Building documentation...
INFO     -  Cleaning site directory
Traceback (most recent call last):
  File "/home/user/.local/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/usr/lib/python3/dist-packages/click/core.py", line 1128, in __call__
    return self.main(*args, **kwargs)
  File "/usr/lib/python3/dist-packages/click/core.py", line 1053, in main
    rv = self.invoke(ctx)
  File "/usr/lib/python3/dist-packages/click/core.py", line 1659, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/usr/lib/python3/dist-packages/click/core.py", line 1395, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/lib/python3/dist-packages/click/core.py", line 754, in invoke
    return __callback(*args, **kwargs)
  File "/home/user/.local/lib/python3.10/site-packages/mkdocs/__main__.py", line 234, in serve_command
    serve.serve(dev_addr=dev_addr, livereload=livereload, watch=watch, **kwargs)
  File "/home/user/.local/lib/python3.10/site-packages/mkdocs/commands/serve.py", line 83, in serve
    builder(config)
  File "/home/user/.local/lib/python3.10/site-packages/mkdocs/commands/serve.py", line 76, in builder
    build(config, live_server=live_server, dirty=dirty)
  File "/home/user/.local/lib/python3.10/site-packages/mkdocs/commands/build.py", line 320, in build
    _build_theme_template(template, env, files, config, nav)
  File "/home/user/.local/lib/python3.10/site-packages/mkdocs/commands/build.py", line 118, in _build_theme_template
    output = _build_template(template_name, template, files, config, nav)
  File "/home/user/.local/lib/python3.10/site-packages/mkdocs/commands/build.py", line 97, in _build_template
    output = template.render(context)
  File "/home/user/.local/lib/python3.10/site-packages/jinja2/environment.py", line 1301, in render
    self.environment.handle_exception()
  File "/home/user/.local/lib/python3.10/site-packages/jinja2/environment.py", line 936, in handle_exception
    raise rewrite_traceback_stack(source=source)
  File "/home/user/.local/lib/python3.10/site-packages/material/404.html", line 4, in top-level template code
    {% extends "main.html" %}
  File "/home/user/.local/lib/python3.10/site-packages/material/main.html", line 4, in top-level template code
    {% extends "base.html" %}
  File "/home/user/.local/lib/python3.10/site-packages/material/base.html", line 148, in top-level template code
    {% block site_nav %}
  File "/home/user/.local/lib/python3.10/site-packages/material/base.html", line 156, in block 'site_nav'
    {% include "partials/nav.html" %}
  File "/home/user/.local/lib/python3.10/site-packages/material/partials/nav.html", line 27, in top-level template code
    {% include "partials/nav-item.html" %}
  File "/home/user/.local/lib/python3.10/site-packages/jinja2/environment.py", line 936, in handle_exception
    raise rewrite_traceback_stack(source=source)
  File "/home/user/dev/faq/overrides/partials/nav-item.html", line 32, in template
    {{nav_item.title|say_hello}}
jinja2.exceptions.TemplateAssertionError: No filter named 'say_hello'.

If i change mkdocs.yml like this

plugins:
  - mkdocs-simple-hooks:
      hooks:
        on_env: "docs.hook:on_env"  # 'hook' instead of 'hooks'

I get the following warning

WARNING  -  Config value 'plugins': Plugin 'mkdocs-simple-hooks': Cannot import module 'docs.hook'.

I conclude that the original configuration file is correct and that it correctly loads the docs/hooks.py file

The declaration of on_env hook seems correct if I follow the docs from Mkdocs and jinja2
https://www.mkdocs.org/dev-guide/plugins/#on_env
https://jinja.palletsprojects.com/en/latest/api/#custom-filters

I don't understand where the problem lies (python declaration ?)

My Mkdocs setup information

mkdocs 1.1.2
mkdocs-material 5.4.0
mkdocs-simple-hooks 0.1.5
mkdocs-static-i18n 0.53

Best regards

Add support for disabling plugin via environment variables

Nice plugin!

I'm considering to use to run some scripts that generates assets (figures, tables) on_pre_build, however I only want to do that when deploying.

MkDocs now has support for environment variables in the mkdocs.yml file (https://www.mkdocs.org/user-guide/configuration/#environment-variables)

I propose adding another argument enabled like so:

- mkdocs-simple-hooks:
     enabled: true
     hooks:
      hook-name: "your.module:hook_function"

Users could then configure an environment variable to optionally switch off:

enabled: !ENV ENABLE_MKDOCS_SIMPLE_HOOKS

Should be very quick to build, here's an example:

If you want I can also provide a PR.

Recommend Projects

React

A declarative, efficient, and flexible JavaScript library for building user interfaces.
Vue.js

🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript

TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
TensorFlow

An Open Source Machine Learning Framework for Everyone
Django

The Web framework for perfectionists with deadlines.
Laravel

A PHP framework for web artisans
D3

Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

javascript

JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
web

Some thing interesting about web. New door for the world.
server

A server is a program made to process requests and deliver data to clients.
Machine learning

Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Visualization

Some thing interesting about visualization, use data art
Game

Some thing interesting about game, make everyone happy.

Recommend Org

Facebook

We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft

Open source projects and samples from Microsoft.
Google

Google ❤️ Open Source for everyone.
Alibaba

Alibaba Open Source for everyone
D3

Data-Driven Documents codes.
Tencent

China tencent open source team.