Fabian Büchler avatar Fabian Büchler committed 4ce5605

Iteration of usage docs.

Comments (0)

Files changed (4)

 ========
 
 .. toctree::
-   :hidden:
-
-   quickstart
-
-.. toctree::
    :maxdepth: 2
 
    installation
    usage
    feincms
 
+.. toctree::
+   :hidden:
+
+   quickstart
+
 Changelog
 =========
 

docs/installation.rst

  Installation
 ==============
 
-The recommended way to install django-markupmirror is with `pip`_ (using
-`easy_install`_ also works)::
+* To **install** django-markupmirror, use `pip`_ (or `easy_install`_ or simply
+  ``python setup.py install`` from source) and add ``'markupmirror'`` to the
+  ``INSTALLED_APPS`` in your `Django`_ project.
 
-    pip instal django-markupmirror
+  .. code-block:: bash
+
+    $ pip install django-markupmirror
+
+  ::
+
+    INSTALLED_APPS = (
+        ...
+        'markupmirror',
+        ...
+    )
+
+* In your ``settings.py`` specify at least ``MARKUPMIRROR_DEFAULT_MARKUP_TYPE``
+  which is ``'plaintext'`` by default.
+
+* For the markup HTML-preview, you'll need to add markupmirror's URLs in your
+  URLconf. In your ``urls.py`` add::
+
+    import markupmirror.urls
+
+    urlpatterns = patterns('',
+        (r'^markupmirror/', include(markupmirror.urls.preview)),
+    )
 
 .. _pip: http://www.pip-installer.org/
 .. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall
 .. _Docutils 0.8+: http://pypi.python.org/pypi/docutils
 .. _Textile 2.1+: http://pypi.python.org/pypi/textile
 
-Markup Types
-------------
-
-The markup-types available by default are:
-
-``plaintext``
-    Plain text markup. Converts URLs to links and linebreaks to breaks and
-    paragraphs.
-
-``html``
-    Allows HTML. Therefore potentially unsafe.
-
-``markdown``
-    Converts `Markdown`_ to HTML.
-
-``restructuredtext``
-    Converts `reStructuredText`_ to HTML.
-
-``textile``
-    Converts `Textile`_ to HTML.
-
 Settings & Configuration
 ------------------------
 
 
 .. py:data:: MARKUPMIRROR_DEFAULT_MARKUP_TYPE
 
-   Defines any of the above markup-types as default for fields where no
-   ``markup_type`` or ``default_markup_type`` has been set explicitly.
+   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``.
 
       This will soon be obsolete due to a generic jQuery plugin to initialize
       the CodeMirror editor anywhere.
 
+
 .. _Markdown: http://daringfireball.net/projects/markdown/
-.. _reStructuredText: http://docutils.sourceforge.net/rst.html
-.. _Textile: http://www.textism.com/tools/textile/
 .. _Markdown's package documentation: http://packages.python.org/Markdown/
 .. _a list of available extensions:
     http://packages.python.org/Markdown/extensions/

docs/quickstart.rst

 Quickstart
 ==========
 
-* To **install** django-markupmirror, use `pip`_ (or `easy_install`_ or simply
-  ``python setup.py install`` from source) and add ``'markupmirror'`` to the
-  ``INSTALLED_APPS`` in your `Django`_ project.
+* To **install** django-markupmirror, use `pip`_ and add ``'markupmirror'`` to
+  the ``INSTALLED_APPS`` in your `Django`_ project.
+
+* In your ``settings.py`` specify at least ``MARKUPMIRROR_DEFAULT_MARKUP_TYPE``
+  which is ``'plaintext'`` by default.
+
+* For the markup HTML-preview, you'll need to add markupmirror's URLs in your
+  URLconf. In your ``urls.py`` add::
+
+    import markupmirror.urls
+
+    urlpatterns = patterns('',
+        (r'^markupmirror/', include(markupmirror.urls.preview)),
+    )
+
+* Add one or more ``markupmirror.fields.MarkupMirrorField`` s to your models
+  and define ``markup_type`` or ``default_markup_type``::
+
+    class ModelWithMarkup(models.Model):
+        content = MarkupMirrorField(
+            verbose_name="content", markup_type='markdown')
 
 * If you want the `FeinCMS`_ content-type model ``MarkupMirrorContent``, you'll
   also need to add ``'markupmirror.feincms'`` to your ``INSTALLED_APPS``.
 
     Page.create_content_type(MarkupMirrorContent)
 
-* In your ``settings.py`` specify at least ``MARKUPMIRROR_DEFAULT_MARKUP_TYPE``
-  which is ``'plaintext'`` by default.
-
-* Add one or more ``markupmirror.fields.MarkupMirrorField`` s to your models
-  and define ``markup_type`` or ``default_markup_type``::
-
-    class ModelWithMarkup(models.Model):
-        content = MarkupMirrorField(
-            verbose_name="content", markup_type='markdown')
-
 By default, django-markupmirror comes with markup converters for plain text
 (converts links and linebreaks) and HTML (does nothing). Converters for
 `Markdown`_, `reStructuredText`_ and `Textile`_ are also available, but require
 =======
  Usage
 =======
+
+Markup-Types
+============
+
+django-markupmirror comes with five default markup types (or converters). You
+Can create and register your own converters and unregister the default ones if
+you prefer.
+
+.. _usage-markup-types-default:
+
+Default Markup Types
+--------------------
+
+The markup-types available by default are:
+
+``plaintext``
+    Plain text markup. Converts URLs to links and linebreaks to breaks and
+    paragraphs.
+
+``html``
+    Allows HTML. Therefore potentially unsafe.
+
+``markdown``
+    Converts `Markdown`_ to HTML.
+
+``restructuredtext``
+    Converts `reStructuredText`_ to HTML.
+
+``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/
+
+The Markup Pool
+---------------
+
+Markup types are registered with the ``markup_pool``.
+
+Create your own Markup Type
+---------------------------
+
+Register and unregister Markup Types
+------------------------------------
+
+
+Using the ``MarkupMirrorField``
+===============================
+
+
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.