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.