Custom Markups

Registering the markup module

A third-party markup is a Python module that can be installed the usual way.

To register your markup class with PyMarkups, make it inherit from AbstractMarkup, and add that class to your module’s entry_points, in the “pymarkups” entry point group.

For example:

setup(
    ...
    entry_points={
        'pymarkups': [
            'mymarkup = mymodule:MyMarkupClass',
        ],
    },
    ...
)

Or using the declarative syntax in setup.cfg:

[options.entry_points]
pymarkups =
    mymarkup = mymodule:MyMarkupClass

See the setuptools documentation on entry points for details.

To check if the module was found by Python-Markups, one can check if the module is present in return value of get_all_markups() function.

Changed in version 3.0: The custom markups should be registered using the entry points mechanism, the pymarkups.txt file is no longer supported.

Importing third-party modules

A markup must not directly import any third party Python module it uses at file level. Instead, it should check the module availability in available() static method.

That method can try to import the needed modules, and return True in case of success, and False in case of failure.

Implementing methods

Any markup must inherit from AbstractMarkup.

Third-party markups must implement AbstractMarkup’s convert() method, which must perform the time-consuming part of markup conversion and return a newly constructed instance of (a subclass of) ConvertedMarkup.

ConvertedMarkup encapsulates the title, body, stylesheet and javascript of a converted document. Of these only the body is required during construction, the others default to an empty string. If additional markup-specific state is required to implement ConvertedMarkup, a subclass can be defined and an instance of it returned from convert() instead.