Commits

Fabian Büchler committed 11dfd09

Added docs on how to create and register new markup converters.

  • Participants
  • Parent commits f60e98c

Comments (0)

Files changed (2)

File docs/usage.rst

 Create your own Markup Type
 ---------------------------
 
-You can easily create your own markup types for any purpose.
+You can easily create your own markup converters for any purpose. The converter
+only needs to inherit from ``BaseMarkup`` and implement the ``convert`` method.
 
+.. autoclass:: markupmirror.markup.base.BaseMarkup
+   :members: convert, before_convert, after_convert, __call__, get_name
+   :special-members:
 
 Register and unregister Markup Types
 ------------------------------------
 
+The :ref:`default markup types <usage-markup-types-default>` provided by
+django-markupmirror are registered during initialization. If you want to remove
+any of these, you can use the ``MarkupPool.unregister_markup`` method::
+
+    from markupmirror.markup.base import markup_pool
+
+    markup_pool.unregister_markup('plaintext')  # is equal to
+    del markup_pool['textile']
+
+To register new markup converters, pass the markup class to the
+``MarkupPool.register_markup`` method::
+
+    from markupmirror.markup.base import markup_pool, BaseMarkup
+
+    class ExampleMarkup(BaseMarkup):
+
+        def convert(self, markup):
+            return markup.replace("markup", "example")
+
+    markup_pool.register_markup(ExampleMarkup)
+
+This would make the ``ExampleMarkup`` converter available through the key
+``example``, derived from its class name::
+
+    example_markup = markup_pool['example']
 
 Using the ``MarkupMirrorField``
 ===============================

File markupmirror/markup/base.py

 class BaseMarkup(object):
     """Basic interface for markup converter classes.
 
+    An example converter could look like this::
+
+        class ExampleMarkup(BaseMarkup):
+
+            def convert(self, markup):
+                return markup.replace("example", "markup")
+
     """
     codemirror_mode = ''
     title = ""
 
     @classmethod
     def get_name(cls):
-        """Returns lowercase markup name, without the "Markup" part."""
+        """Returns lowercase markup name, without the "Markup" part.
+
+        Class naming convention is ``<Markup-Type>Markup``.
+        """
         return cls.__name__.replace("Markup", "", 1).lower()
 
+    def convert(self, markup):
+        """Main conversion method. Must be implemented in subclasses."""
+        return markup
+
     def before_convert(self, markup):
-        """Called before ``convert``."""
+        """Called before ``convert``. Can be used to separate the main
+        conversion through a third-party library (e.g. Markdown) from
+        additional logic.
+
+        """
         return markup
 
     def after_convert(self, markup):
-        """``Called after ``convert``."""
-        return markup
-
-    def convert(self, markup):
-        """Main conversion method. Use third-pary libraries here."""
+        """Called after ``convert``. Similar to ``before_convert``."""
         return markup
 
     def __call__(self, markup):