Docs for markup module

docs/developers/index.rst

@@ -46,3 +46,4 @@ Following references cover everything you want to know about writing your own ap
    validators
    auth
    acls
+   markup

docs/developers/markup.rst

@@ -0,0 +1,56 @@
+=============
+Misago Markup
+=============
+
+Misago defines custom ``misago.markup`` module that provides facilities for parsing strings.
+
+This module exposes following functions as its public API:
+
+
+parse
+-----
+
+.. function:: parse(text, author=None, allow_mentions=True, allow_links=True, allow_images=True, allow_blocks=True)
+
+Parses Misago-flavoured Markdown text according to settings provided. Returns dictionary with following keys:
+
+* ``original_text``: original text that was parsed
+* ``parsed_text``: parsed text
+* ``markdown``: markdown instance
+
+
+common_flavour
+--------------
+
+.. function:: common_flavour(text, author=None, allow_mentions=True)
+
+Convenience function that wraps ``parse()``. This function is used for parsing messages.
+
+
+limited_flavour
+--------------
+
+.. function:: limited_flavour(text)
+
+Convenience function that wraps ``parse()``. This function is used for parsing short messages and supports only subset of full markup. Unlike other functions, this one returns parsed string instead of dict.
+
+
+Extending Markup
+================
+
+To extend Misago markup, create custom module defining one or both of following functions:
+
+
+.. function:: extend_markdown(md)
+
+Defining this function will allow you to register new extensions in markdown used to parse text.
+
+
+.. function:: process_result(result, soup)
+
+This function is called to allow additional changes in result dict as well as extra instrospection and cleanup of parsed text, which is provided as `Beautiful Soup <http://www.crummy.com/software/BeautifulSoup/bs4/doc/>`_ class instance.
+
+
+Both functions should modify provided arguments in place.
+
+Once your functions are done, add path to your module to ``MISAGO_MARKUP_EXTENSIONS`` setting which is tupe of modules.

docs/developers/settings.rst

@@ -188,6 +188,12 @@ MISAGO_MAILER_BATCH_SIZE
 Default maximum size of single mails package that Misago will build before sending mails and creating next package.
 
 
+MISAGO_MARKUP_EXTENSIONS
+------------------------
+
+List of python modules extending Misago markup.
+
+
 password_complexity
 -------------------
 

docs/index.rst

@@ -35,3 +35,4 @@ Table of Contents
    developers/validators
    developers/auth
    developers/acls
+   developers/markup