Fabian Büchler avatar Fabian Büchler committed 2175862

Added more usage docs for the MarkupMirrorField.

Comments (0)

Files changed (5)

 The markup-types available by default are:
 
 ``plaintext``
-    Plain text markup. Converts URLs to links and linebreaks to breaks and
-    paragraphs.
+    .. automodule:: markupmirror.markup.plaintext
+    .. autoclass:: PlainTextMarkup
 
 ``html``
-    Allows HTML. Therefore potentially unsafe.
+    .. automodule:: markupmirror.markup.html
+    .. autoclass:: HtmlMarkup
 
 ``markdown``
-    Converts `Markdown`_ to HTML.
+    .. automodule:: markupmirror.markup.markdown_
+    .. autoclass:: MarkdownMarkup
 
 ``restructuredtext``
-    Converts `reStructuredText`_ to HTML.
+    .. automodule:: markupmirror.markup.restructuredtext
+    .. autoclass:: ReStructuredTextMarkup
 
 ``textile``
-    Converts `Textile`_ to HTML.
-
-.. _Markdown: http://daringfireball.net/projects/markdown/
-.. _reStructuredText: http://docutils.sourceforge.net/rst.html
-.. _Textile: http://www.textism.com/tools/textile/
+    .. automodule:: markupmirror.markup.textile_
+    .. autoclass:: TextileMarkup
 
 The Markup Pool
 ---------------
 The markup pool is the main access point to markup converters. They are
 registered with the pool, and retrieved from it.
 
+.. automodule:: markupmirror.markup.base
+
 .. py:data:: markupmirror.markup.base.markup_pool
 
    Instance of ``MarkupPool`` for public use.
 
-.. autoclass:: markupmirror.markup.base.MarkupPool
+.. autoclass:: MarkupPool
    :members:
 
 Create your own Markup Type
 Using the ``MarkupMirrorField``
 ===============================
 
+After you have configured markupmirror in your settings and added your custom
+markup converters, the only thing left to do is to use the
+``MarkupMirrorField`` in your models.
 
+A field with fixed markup type would have to provide a ``markup_type``::
+
+    from django.db import models
+    from markupmirror.fields import MarkupMirrorFields
+
+    class MyModel(models.Model):
+        content = MarkupMirrorField(markup_type='markdown')
+
+To provide a selectbox for the users to select the content's markup type
+manually, use ``default_markup_type`` instead::
+
+    class MyModel(models.Model):
+        content = MarkupMirrorField(default_markup_type='plaintext')
+
+If you provide neither ``markup_type`` nor ``default_markup_type``, the
+``MARKUPMIRROR_DEFAULT_MARKUP_TYPE`` setting will be used as default.
+
+For reference, see the ``MarkupMirrorField`` and ``Markup`` classes:
+
+.. automodule:: markupmirror.fields
+
+.. autoclass:: MarkupMirrorField
+
+.. autoclass:: Markup
+   :members: raw, markup_type, rendered, __unicode__
+   :special-members:

markupmirror/fields.py

     Stores the names of the associated field, the rendered field and the
     markup_type field to make assignment possible.
 
+    When accessing the value of a ``MarkupField``, a ``Markup`` instance will
+    be returned. This provides a few methods to access the raw and rendered
+    markup, and the markup type of the saved content.
+
     """
     def __init__(self, instance, field_name,
                  rendered_field_name, markup_type_field_name):
 
     @property
     def raw(self):
+        """The raw markup content."""
         return self.instance.__dict__[self.field_name]
 
     @raw.setter
 
     @property
     def markup_type(self):
+        """Markup type of the current markup content."""
         return self.instance.__dict__[self.markup_type_field_name]
 
     @markup_type.setter
 
     @property
     def rendered(self):
+        """Returns the rendered markup content (read only). This is only
+        available after ``Model.save`` has been called.
+
+        """
         return getattr(self.instance, self.rendered_field_name)
 
     def __unicode__(self):
-        """Allows display via templates to work without safe filter."""
+        """Allows display via templates to work without safe filter. Same as
+        ``rendered``.
+
+        """
         return mark_safe(self.rendered)
 
 
 class MarkupMirrorField(models.TextField):
     """Field to store markup content.
 
-    MarkupMirrorField adds three fields to the model it is used in.
+    The ``MarkupMirrorField`` adds three fields to the model it is used in.
 
-    * One field for the raw markup content.
-    * One field for the rendered HTML content.
-    * One field that specifies the markup type.
+    * One field for the raw markup content (``<field_name>``).
+    * One field for the rendered HTML content (``<field_name>_rendered``).
+    * One field that specifies the markup type (``<field_name>_markup_type``).
+
+    The field can be used with a fixed ``markup_type`` or a
+    ``default_markup_type``, which displays an additional selection widget
+    for the available markup types. However, only one of ``markup_type`` and
+    ``default_markup_type`` can be provided.
+
+    If neither is provided, the setting ``MARKUPMIRROR_DEFAULT_MARKUP_TYPE``
+    is used as ``default_markup_type`` instead.
 
     """
     def __init__(self, verbose_name=None, name=None,
             raise ImproperlyConfigured(
                 "Cannot specify both markup_type and default_markup_type")
 
-        self.MARKUPMIRROR_DEFAULT_MARKUP_TYPE = markup_type or default_markup_type
+        self.default_markup_type = markup_type or default_markup_type
         self.markup_type_editable = markup_type is None
         self.escape_html = escape_html
 
-        if (self.MARKUPMIRROR_DEFAULT_MARKUP_TYPE and
-            self.MARKUPMIRROR_DEFAULT_MARKUP_TYPE not in markup_pool):
+        if (self.default_markup_type and
+            self.default_markup_type not in markup_pool):
             raise ImproperlyConfigured(
                 "Invalid default_markup_type for field '%r', "
                 "available types: %s" % (
                     key=lambda markup: markup[1].title.lower())]
             markup_type_field = models.CharField(
                 choices=choices, max_length=30,
-                default=self.MARKUPMIRROR_DEFAULT_MARKUP_TYPE, blank=self.blank,
+                default=self.default_markup_type, blank=self.blank,
                 editable=self.markup_type_editable)
             markup_type_field.creation_counter = self.creation_counter + 1
 
         widget_attrs = {
             'class': 'item-markupmirror',
         }
-        if (self.MARKUPMIRROR_DEFAULT_MARKUP_TYPE and
-            self.MARKUPMIRROR_DEFAULT_MARKUP_TYPE in markup_pool):
+        if (self.default_markup_type and
+            self.default_markup_type in markup_pool):
             widget_attrs['data-mode'] = markup_pool[
-                self.MARKUPMIRROR_DEFAULT_MARKUP_TYPE].codemirror_mode
-            widget_attrs['data-markuptype'] = self.MARKUPMIRROR_DEFAULT_MARKUP_TYPE
+                self.default_markup_type].codemirror_mode
+            widget_attrs['data-markuptype'] = self.default_markup_type
 
         defaults = {
             'widget': widgets.MarkupMirrorTextarea(attrs=widget_attrs),

markupmirror/markup/markdown_.py

 
 
 class MarkdownMarkup(BaseMarkup):
-    """Markup transformer for Markdown content.
+    """Markup transformer for `Markdown`_ content.
+
+    .. _Markdown: http://daringfireball.net/projects/markdown/
 
     """
     codemirror_mode = 'text/x-markdown'

markupmirror/markup/restructuredtext.py

 
 
 class ReStructuredTextMarkup(BaseMarkup):
-    """Markup transformer for reStructuredText content.
+    """Markup transformer for `reStructuredText`_ content.
+
+    .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 
     """
     codemirror_mode = 'text/x-rst'

markupmirror/markup/textile_.py

 
 
 class TextileMarkup(BaseMarkup):
-    """Markup transformer for Textile content.
+    """Markup transformer for `Textile`_ content.
+
+    .. _Textile: http://www.textism.com/tools/textile/
 
     """
     codemirror_mode = 'text/plain'
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.