Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

Loaders Based Plugin API

kk edited this page Oct 21, 2016 · 4 revisions

Proposal

This is a proposal for a Plugin API based on loaders. Loader is used for convert raw files into html content.

Create loader

# my_loader.py
class MyLoader:

    def __init__(options):
        """Configure your loader with options"""

    def accept(self, filename):
        """Decide load the file or not"""

    def load(self, page):
        """Load page"""
        # the page object contains all info of which should be load
        # the return value contains all info of which should be write
        return MkdocsResponse()

Register loaders

# setup.py
entry_points = {
    'mkdocs.loaders': [
        'my_loader = path.to.my_loader:MyLoader',
    ]
}

Activating Loaders

# mkdocs.yml
loaders:
    - name: "my_loader"
      options: "options"

Implementation

# changes in mkdocs.config.load_config
def load_config(config_file=None, **kwargs):
    # ...do somethings
    loaders = []
    # instance loaders
    cfg["loaders"] = loaders

# changes in mkdocs.commands.build.py
def _build_page(page, config):
    for loader in config["loaders"]:
        if loader.accept(page.input_path):
            return loader.load(page)
    raise ValueError("Can't find loader for {}".format(page.input_path))

# also, create a markdown loader and register it as builtin loader
class MarkdownLoader:
    def accept(self, filename):
        # accept markdown file
        pass

    def load(page):
        # some code of origin _build_page
        pass

Example

A autodoc loader.
Live Demo: http://restaction.readthedocs.io/zh_CN/latest/api/

Usage

docs/api.autodoc

mkdocs_autodoc
mkdocs_autodoc::Demo

mkdocs.yml

site_name: Demo
pages:
  - Home: index.md
  - API: api.autodoc

Loader

class AutodocLoader:
    def accept(self, filename):
        # accept *.autodoc file
        pass

    def load(page):
        # parse *.autodoc file, generate html content
        pass

See also

https://groups.google.com/forum/#!topic/mkdocs/7x2u9iN7gdk

Clone this wiki locally

Morty Proxy This is a proxified and sanitized view of the page, visit original site.