1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
|
==============
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
:class:`~markups.abstract.AbstractMarkup`, and add that class to
your module's ``entry_points``, in the “pymarkups” entry point group.
For example:
.. code-block:: toml
:caption: pyproject.toml
[project.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
:func:`~markups.get_all_markups` function.
.. versionchanged:: 3.0
The custom markups should be registered using the entry points
mechanism, the ``pymarkups.txt`` file is no longer supported.
.. _`setuptools documentation`: https://setuptools.pypa.io/en/latest/userguide/entry_point.html
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
:meth:`~markups.abstract.AbstractMarkup.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 :class:`~markups.abstract.AbstractMarkup`.
Third-party markups must implement :class:`~markups.abstract.AbstractMarkup`'s
:meth:`~markups.abstract.AbstractMarkup.convert` method, which must perform the
time-consuming part of markup conversion and return a newly constructed
instance of (a subclass of) :class:`~markups.abstract.ConvertedMarkup`.
:class:`~markups.abstract.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
:class:`~markups.abstract.ConvertedMarkup`, a subclass can be defined and an
instance of it returned from :meth:`~markups.abstract.AbstractMarkup.convert`
instead.
|
