Anonymous avatar Anonymous committed 3faccfc

Started writing usage docs.

Comments (0)

Files changed (11)

 
 import os
 
+from django.core.management import setup_environ
+
 import markupmirror
+import tests.settings
 
 
+# setup django environment for autodoc
+setup_environ(tests.settings)
+
 # switch for different configuration on Read the Docs
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc']
+autodoc_member_order = 'bysource'
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
    usage
    feincms
 
+* :ref:`modindex`
+
 .. toctree::
    :hidden:
 

docs/installation.rst

 Use the configuration variables below in your ``settings.py`` to customize the
 behaviour of django-markupmirror:
 
-.. py:data:: MARKUPMIRROR_DEFAULT_MARKUP_TYPE
-
-   Defines any of the :ref:`default markup-types <usage-markup-types-default>`
-   as default for fields where no ``markup_type`` or ``default_markup_type``
-   has been set explicitly.
-
-   Defaults to ``plaintext``.
-
-.. py:data:: MARKUPMIRROR_MARKDOWN_EXTENSIONS
-
-   Defines the extensions to load for `Markdown`_. Markdown's package
-   documentation contains `a list of available extensions`_.
-
-   Defaults to ``['extra', 'headerid(level=2)']``.
-
-.. py:data:: MARKUPMIRROR_MARKDOWN_OUTPUT_FORMAT
-
-   Defines the output format for Markdown. One of ``HTML4``, ``XHTML`` and
-   ``HTML5``.
-
-   Defaults to ``HTML5``.
-
-.. py:data:: MARKUPMIRROR_TEXTILE_SETTINGS
-
-   Dictionary of arguments passed directly to the Textile converter defined in
-   ``textile.functions.textile``.
-
-   The converter's default function signature is:
-   ``head_offset=0, html_type='xhtml', auto_link=False, encoding=None,
-   output=None``.
-
-   Defaults to: ``{'encoding': 'utf-8', 'output': 'utf-8'}``
-
-.. py:data:: MARKUPMIRROR_FEINCMS_INIT_TEMPLATE
-
-   Defines the template used by FeinCMS to initialize Pages with
-   ``MarkupMirrorContent`` blocks.
-
-   .. deprecated:: 0.1a2
-      This will soon be obsolete due to a generic jQuery plugin to initialize
-      the CodeMirror editor anywhere.
-
-.. py:data:: MARKUPMIRROR_FEINCMS_INIT_CONTEXT
-
-   Context passed to the ``MARKUPMIRROR_FEINCMS_INIT_TEMPLATE``.
-
-   .. deprecated:: 0.1a2
-      This will soon be obsolete due to a generic jQuery plugin to initialize
-      the CodeMirror editor anywhere.
-
-
-.. _Markdown: http://daringfireball.net/projects/markdown/
-.. _Markdown's package documentation: http://packages.python.org/Markdown/
-.. _a list of available extensions:
-    http://packages.python.org/Markdown/extensions/
+.. automodule:: markupmirror.settings
+   :members:
 The Markup Pool
 ---------------
 
-Markup types are registered with the ``markup_pool``.
+The markup pool is the main access point to markup converters. They are
+registered with the pool, and retrieved from it.
+
+.. autodata:: markupmirror.markup.base.markup_pool
+
+.. autoclass:: markupmirror.markup.base.MarkupPool
+   :members:
 
 Create your own Markup Type
 ---------------------------
 
+You can easily create your own markup types for any purpose.
+
+
 Register and unregister Markup Types
 ------------------------------------
 

markupmirror/feincms/models.py

     # __name__ = 'richtextcontent'
 
     feincms_item_editor_context_processors = (
-        lambda x: settings.FEINCMS_INIT_CONTEXT,
+        lambda x: settings.MARKUPMIRROR_FEINCMS_INIT_CONTEXT,
     )
     feincms_item_editor_includes = {
-        'head': [settings.FEINCMS_INIT_TEMPLATE],
+        'head': [settings.MARKUPMIRROR_FEINCMS_INIT_TEMPLATE],
     }
 
     content = MarkupMirrorField(
         verbose_name=_(u"Markup content"),
-        markup_type=settings.DEFAULT_MARKUP_TYPE,
+        markup_type=settings.MARKUPMIRROR_DEFAULT_MARKUP_TYPE,
         blank=True)
 
     class Meta:

markupmirror/fields.py

             raise ImproperlyConfigured(
                 "Cannot specify both markup_type and default_markup_type")
 
-        self.default_markup_type = markup_type or default_markup_type
+        self.MARKUPMIRROR_DEFAULT_MARKUP_TYPE = markup_type or default_markup_type
         self.markup_type_editable = markup_type is None
         self.escape_html = escape_html
 
-        if (self.default_markup_type and
-            self.default_markup_type not in markup_pool):
+        if (self.MARKUPMIRROR_DEFAULT_MARKUP_TYPE and
+            self.MARKUPMIRROR_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.default_markup_type, blank=self.blank,
+                default=self.MARKUPMIRROR_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.default_markup_type and
-            self.default_markup_type in markup_pool):
+        if (self.MARKUPMIRROR_DEFAULT_MARKUP_TYPE and
+            self.MARKUPMIRROR_DEFAULT_MARKUP_TYPE in markup_pool):
             widget_attrs['data-mode'] = markup_pool[
-                self.default_markup_type].codemirror_mode
-            widget_attrs['data-markuptype'] = self.default_markup_type
+                self.MARKUPMIRROR_DEFAULT_MARKUP_TYPE].codemirror_mode
+            widget_attrs['data-markuptype'] = self.MARKUPMIRROR_DEFAULT_MARKUP_TYPE
 
         defaults = {
             'widget': widgets.MarkupMirrorTextarea(attrs=widget_attrs),

markupmirror/markup/base.py

     def unregister_markup(self, markup_name):
         """Unregisters a markup converter with the name ``markup_name``.
         Fails silently if no converter was registered by that name.
+
+        Alternatively you can also use the ``del`` operator::
+
+           del markup_pool['restructuredtext']
+
         """
         if markup_name in self.markups:
             del self.markups[markup_name]
 
-    def has_markup(self, name):
-        return name in self.markups
+    def has_markup(self, markup_name):
+        """Tests if a markup converter with the name ``markup_name`` is already
+        registered with the markup pool.
 
-    def get_markup(self, name):
-        """Returns one markup converter by name.
-        Raises ``KeyError`` if no converter was registered by ``name``.
+        Alternatively you can also use the ``in`` operator, like with a
+        dictionary::
+
+            if 'restructuredtext' in markup_pool:
+                pass
 
         """
-        return self.markups[name]
+        return markup_name in self.markups
+
+    def get_markup(self, markup_name):
+        """Returns one markup converter by name.
+        Raises ``KeyError`` if no converter was registered by ``markup_name``.
+
+        Alternatively you can also use the ``[]`` accessor, like with a
+        dictionary::
+
+            markup = markup_pool['restructuredtext']
+
+        """
+        return self.markups[markup_name]
 
     def __contains__(self, key):
         return self.has_markup(key)
 
 
 markup_pool = MarkupPool()
+"""Instance of ``MarkupPool`` for public use."""
+
 register_markup = markup_pool.register_markup
 
 

markupmirror/markup/markdown_.py

     title = _(u"Markdown")
 
     def __init__(self):
-        self.extensions = settings.MARKDOWN_EXTENSIONS
-        self.output_format = settings.MARKDOWN_OUTPUT_FORMAT
+        self.extensions = settings.MARKUPMIRROR_MARKDOWN_EXTENSIONS
+        self.output_format = settings.MARKUPMIRROR_MARKDOWN_OUTPUT_FORMAT
         self.markdown = Markdown(
             extensions=self.extensions,
             output_format=self.output_format)

markupmirror/markup/textile_.py

     title = _(u"Textile")
 
     def __init__(self):
-        self.textile_settings = settings.TEXTILE_SETTINGS
+        self.textile_settings = settings.MARKUPMIRROR_TEXTILE_SETTINGS
         self.textile = textile
 
     def convert(self, markup):

markupmirror/settings.py

 from django.conf import settings
 
 
-# Default markup type
-# Used for fields which have no markup_type or default_markup_type assigned
-# before a markup_type has been selected by the user (selectbox).
-DEFAULT_MARKUP_TYPE = getattr(settings,
+MARKUPMIRROR_DEFAULT_MARKUP_TYPE = getattr(settings,
     'MARKUPMIRROR_DEFAULT_MARKUP_TYPE', 'plaintext')
+"""Defines any of the :ref:`default markup-types <usage-markup-types-default>`
+as default for fields where no ``markup_type`` or ``default_markup_type``
+has been set explicitly.
 
+Defaults to ``plaintext``.
+
+"""
 
 # CodeMirror settings
 
 # Settings for markup converters
 
 # Extensions and settings for markdown
-MARKDOWN_EXTENSIONS = getattr(settings,
+MARKUPMIRROR_MARKDOWN_EXTENSIONS = getattr(settings,
     'MARKUPMIRROR_MARKDOWN_EXTENSIONS',
     ['extra', 'headerid(level=2)'])
-MARKDOWN_OUTPUT_FORMAT = getattr(settings,
+"""Defines the extensions to load for `Markdown`_. `Markdown's package
+documentation`_ contains `a list of available extensions`_.
+
+Defaults to ``['extra', 'headerid(level=2)']``.
+
+.. _Markdown: http://daringfireball.net/projects/markdown/
+.. _Markdown's package documentation: http://packages.python.org/Markdown/
+.. _a list of available extensions:
+    http://packages.python.org/Markdown/extensions/
+
+"""
+MARKUPMIRROR_MARKDOWN_OUTPUT_FORMAT = getattr(settings,
     'MARKUPMIRROR_MARKDOWN_OUTPUT_FORMAT',
     'html5')
+"""Defines the output format for Markdown. One of ``HTML4``, ``XHTML`` and
+``HTML5``.
+
+Defaults to ``HTML5``.
+
+"""
 
 # Textile settings
-TEXTILE_SETTINGS = getattr(settings,
+MARKUPMIRROR_TEXTILE_SETTINGS = getattr(settings,
     'MARKUPMIRROR_TEXTILE_SETTINGS',
     {'encoding': 'utf-8', 'output': 'utf-8'})
+"""Dictionary of arguments passed directly to the Textile converter defined in
+``textile.functions.textile``.
+
+The converter's default function signature is:
+``head_offset=0, html_type='xhtml', auto_link=False, encoding=None,
+output=None``.
+
+Defaults to: ``{'encoding': 'utf-8', 'output': 'utf-8'}``
+
+"""
 
 
 # Settings for MarkupMirrorContent for FeinCMS
 
 # Init template for CodeMirror in FeinCMS
-FEINCMS_INIT_TEMPLATE = getattr(settings,
+MARKUPMIRROR_FEINCMS_INIT_TEMPLATE = getattr(settings,
     'MARKUPMIRROR_FEINCMS_INIT_TEMPLATE',
     'admin/markupmirror/feincms/init_codemirror.html')
+"""Defines the template used by FeinCMS to initialize Pages with
+``MarkupMirrorContent`` blocks.
 
+.. deprecated:: 0.1a2
+   This will soon be obsolete due to a generic jQuery plugin to initialize
+   the CodeMirror editor anywhere.
+
+"""
 # Context for init template
-FEINCMS_INIT_CONTEXT = getattr(settings,
+MARKUPMIRROR_FEINCMS_INIT_CONTEXT = getattr(settings,
     'MARKUPMIRROR_FEINCMS_INIT_CONTEXT', {
     #     'CODEMIRROR_JS': CODEMIRROR_JS,
     #     'CODEMIRROR_CSS': CODEMIRROR_CSS,
         'CODEMIRROR_WIDTH': '50%',
         'CODEMIRROR_HEIGHT': '300px',
     })
+"""Context passed to the ``MARKUPMIRROR_FEINCMS_INIT_TEMPLATE``.
+
+.. deprecated:: 0.1a2
+   This will soon be obsolete due to a generic jQuery plugin to initialize
+   the CodeMirror editor anywhere.
+
+"""

markupmirror/widgets.py

             # get real value
             value = value.raw
         else:
-            default = settings.DEFAULT_MARKUP_TYPE
+            default = settings.MARKUPMIRROR_DEFAULT_MARKUP_TYPE
             default_attrs = {
                 'data-mode': markup_pool[default].codemirror_mode,
                 'data-markuptype': default,
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.