From eb07823613a25760991c3ceb2e301be0368ca7ca Mon Sep 17 00:00:00 2001 From: Carl Meyer Date: Fri, 26 Jun 2009 11:25:49 -0400 Subject: [PATCH] docs and setup.py updates --- INSTALL.txt | 12 ---- MANIFEST.in | 2 - README.txt | 152 +++++++++++++++++++++++++++++++++++++++++++--- docs/overview.txt | 149 --------------------------------------------- setup.py | 3 +- 5 files changed, 146 insertions(+), 172 deletions(-) delete mode 100644 INSTALL.txt delete mode 100644 docs/overview.txt diff --git a/INSTALL.txt b/INSTALL.txt deleted file mode 100644 index edbed6e..0000000 --- a/INSTALL.txt +++ /dev/null @@ -1,12 +0,0 @@ -To install django-markitup, run the following command inside this -directory: - - python setup.py install - -You can also just copy the included ``markitup`` directory somewhere -on your Python path, or symlink to it from somewhere on your Python path; -this is useful if you're working from a Subversion checkout. - -This application requires Python 2.3 or later, and Django 1.0 or later. -You can obtain Python from http://www.python.org/ and Django from -http://www.djangoproject.com/. diff --git a/MANIFEST.in b/MANIFEST.in index 88cd626..cb92ab4 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,7 +1,5 @@ include AUTHORS.txt include CHANGELOG.txt -include INSTALL.txt include LICENSE.txt include MANIFEST.in include README.txt -recursive-include docs * \ No newline at end of file diff --git a/README.txt b/README.txt index b8a3fee..d5fa700 100644 --- a/README.txt +++ b/README.txt @@ -2,15 +2,151 @@ django-markitup =============== -This application provides convenient integration of the MarkItUp_ -markup editor widget (by Jay Salvat) in Django projects, via a custom -form widget. It also provides server-side support for MarkItUp!'s -AJAX preview. +Easy integration of the MarkItUp_ markup editor widget (by Jay Salvat) in +Django projects. Includes server-side support for MarkItUp!'s AJAX preview. -For installation instructions, see the file "INSTALL.txt" in this -directory; for instructions on how to use this application, and on -what it provides, see the file "overview.txt" in the "docs/" -directory. .. _MarkItUp: http://markitup.jaysalvat.com/ +Installation +============ + +Download a release tarball from Launchpad_, or get the Bazaar trunk +version of the application:: + + bzr checkout lp:django-markitup django-markitup + +To install django-markitup: + + 1. Put the ``markitup`` folder on your Python path (or use ``python + setup.py install``, easy_install, or pip). + + 2. Add ``'markitup'`` to your ``INSTALLED_APPS`` setting (not actually + necessary, but probably a good idea). + + 3. Make the contents of the "markitup/media/markitup" directory + available at ``MEDIA_URL/markitup``. This can be done by copying the + files, making a symlink, or through your webserver configuration. + + 4. If you want to use AJAX-based preview: + + - Add ``url(r'^markitup/', include('markitup.urls')`` in your + root URLconf. + - Set the MARKITUP_PREVIEW_FILTER setting (see `Using AJAX preview`_ + below). + +.. _Launchpad: http://launchpad.net/django-markitup + +Using the MarkItUp! widget +========================== + +The MarkItUp! widget lives at ``markitup.widgets.MarkItUpWidget``, and +can be used like any other Django custom widget. + +To assign it to a form field:: + + from markitup.widgets import MarkItUpWidget + ... + content = forms.TextField(widget=MarkItUpWidget()) + +When this form is displayed on your site, you must include the form +media somewhere on the page using ``{{ form.media }}``, or the +MarkItUpWidget will have no effect. + +To use MarkItUpWidget in the Django admin: + + from markitup.widgets import MarkItUpWidget + + class MyModelAdmin(admin.ModelAdmin): + ... + def formfield_for_dbfield(self, db_field, **kwargs): + if db_field.name == 'content': + kwargs['widget'] = MarkItUpWidget(attrs={'class': 'vLargeTextField'}) + return super(MyModelAdmin, self).formfield_for_dbfield(db_field, **kwargs) + +You can also use the formfield_overrides attribute of the ModelAdmin, which +is simpler but only allows setting the widget per field type (so it isn't +possible to use the MarkItUpWidget on one TextField in a model and not +another). + +Choosing a MarkItUp! button set and skin +======================================== + +MarkItUp! allows the toolbar button-set to be customized in a +Javascript settings file. By default, django-markitup uses the +"default" set (meant for HTML editing). Django-markitup also includes +basic "markdown" and "textile" sets (these are the sets available from +`the MarkItUp site `_, modified only to +add previewParserPath). + +To use an alternate set, assign the ``MARKITUP_SET`` setting a URL +path (absolute or relative to MEDIA_URL) to the set directory. For +instance, to use the "markdown" set included with django-markitup:: + + MARKITUP_SET = 'markitup/sets/markdown' + +MarkItUp! skins can be specified in a similar manner. Both "simple" +and "markitup" skins are included, by default "simple" is used. To +use the "markitup" skin instead:: + + MARKITUP_SKIN = 'markitup/skins/markitup' + +Neither of these settings has to refer to a location inside +django-markitup's media. You can define your own sets and skins and +store them anywhere, as long as you set the MARKITUP_SET and +MARKITUP_SKIN settings to the appropriate URLs. + +Set and skin may also be chosen on a per-widget basis by passing the +``markitup_set`` and ``markitup_skin`` keyword arguments to +MarkItUpWidget. + + +Using AJAX preview +================== + +If you've included ``markitup.urls`` in your root URLconf (as +demonstrated above under `Installation`_), all you need to enable +server-side AJAX preview is the ``MARKITUP_PREVIEW_FILTER`` setting. + +``MARKITUP_PREVIEW_FILTER`` must be a two-tuple. + +The first element must be a string, the Python dotted path to a markup +filter function. This function should accept markup as its first +argument and return HTML. It may accept other keyword arguments as +well. You may parse your markup for preview using any method you +choose, as long as you can wrap it in a function that meets these +criteria. + +The second element must be a dictionary of keyword arguments to pass +to the filter function. The dictionary may be empty. + +For example, if you have python-markdown installed, you could use it +like this:: + + MARKITUP_PREVIEW_FILTER = ('markdown.markdown', {'safe_mode': True}) + +Alternatively, you could use the "textile" filter provided by Django +like this:: + + MARKITUP_PREVIEW_FILTER = ('django.contrib.markup.templatetags.markup.textile', {}) + +(The textile filter function doesn't accept keyword arguments, so the +kwargs dictionary must be empty in this case.) + +**Note:** If you use your own custom MarkItUp! set, be sure to set the + ``previewParserPath`` option to ``'/markitup/preview/'``. + + +Other settings +============== + +MarkItUp! requires the jQuery Javascript library. By default, +django-markitup links to the most recent minor version of jQuery 1.3 +available at ajax.googleapis.com (via the URL +``http://ajax.googleapis.com/ajax/libs/jquery/1.3/jquery.min.js``). +If you wish to use a different version of jQuery, or host it yourself, +set the JQUERY_URL setting. For example:: + + JQUERY_URL = 'jquery.min.js' + +This will use the jQuery available at MEDIA_URL/jquery.min.js. diff --git a/docs/overview.txt b/docs/overview.txt deleted file mode 100644 index 6623439..0000000 --- a/docs/overview.txt +++ /dev/null @@ -1,149 +0,0 @@ -=============== -django-markitup -=============== - -Easy integration of the MarkItUp_ markup editor widget in Django projects. - - -.. _MarkItUp: http://markitup.jaysalvat.com/ - -Installation -============ - -Download a release tarball from Launchpad_, or get the Bazaar trunk -version of the application:: - - bzr checkout lp:django-markitup django-markitup - -To install django-markitup: - - 1. Put the ``markitup`` folder somewhere on your Python path. - - 2. Put ``'markitup'`` in your ``INSTALLED_APPS`` setting. - - 3. Make the contents of the "markitup/media/markitup" directory - available at ``MEDIA_URL/markitup``. This can be done by copying the - files, making a symlink, or through your webserver configuration. - - 4. If you want to use AJAX-based preview: - - - Add ``url(r'^markitup/', include('markitup.urls')`` in your - root URLconf. - - Set the MARKITUP_PREVIEW_FILTER setting (see `Using AJAX preview`_ - below). - -.. _Launchpad: http://launchpad.net/django-markitup - -Using the MarkItUp! widget -========================== - -The MarkItUp! widget lives at ``markitup.widgets.MarkItUpWidget``, and -can be used like any other Django custom widget. - -To assign it to a form field:: - - from markitup.widgets import MarkItUpWidget - ... - content = forms.TextField(widget=MarkItUpWidget()) - -When this form is displayed on your site, you must include the form -media somewhere on the page using ``{{ form.media }}``, or the -MarkItUpWidget will have no effect. - -To use MarkItUpWidget in the Django admin: - - from markitup.widgets import MarkItUpWidget - - class MyModelAdmin(admin.ModelAdmin): - ... - def formfield_for_dbfield(self, db_field, **kwargs): - if db_field.name == 'content': - kwargs['widget'] = MarkItUpWidget(attrs={'class': 'vLargeTextField'}) - return super(MyModelAdmin, self).formfield_for_dbfield(db_field, **kwargs) - -You can also use the formfield_overrides attribute of the ModelAdmin, which -is simpler but only allows setting the widget per field type (so it isn't -possible to use the MarkItUpWidget on one TextField in a model and not -another). - -Choosing a MarkItUp! button set and skin -======================================== - -MarkItUp! allows the toolbar button-set to be customized in a -Javascript settings file. By default, django-markitup uses the -"default" set (meant for HTML editing). Django-markitup also includes -basic "markdown" and "textile" sets (these are the sets available from -`the MarkItUp site `_, modified only to -add previewParserPath). - -To use an alternate set, assign the ``MARKITUP_SET`` setting a URL -path (absolute or relative to MEDIA_URL) to the set directory. For -instance, to use the "markdown" set included with django-markitup:: - - MARKITUP_SET = 'markitup/sets/markdown' - -MarkItUp! skins can be specified in a similar manner. Both "simple" -and "markitup" skins are included, by default "simple" is used. To -use the "markitup" skin instead:: - - MARKITUP_SKIN = 'markitup/skins/markitup' - -Neither of these settings has to refer to a location inside -django-markitup's media. You can define your own sets and skins and -store them anywhere, as long as you set the MARKITUP_SET and -MARKITUP_SKIN settings to the appropriate URLs. - -Set and skin may also be chosen on a per-widget basis by passing the -``markitup_set`` and ``markitup_skin`` keyword arguments to -MarkItUpWidget. - - -Using AJAX preview -================== - -If you've included ``markitup.urls`` in your root URLconf (as -demonstrated above under `Installation`_), all you need to enable -server-side AJAX preview is the ``MARKITUP_PREVIEW_FILTER`` setting. - -``MARKITUP_PREVIEW_FILTER`` must be a two-tuple. - -The first element must be a string, the Python dotted path to a markup -filter function. This function should accept markup as its first -argument and return HTML. It may accept other keyword arguments as -well. You may parse your markup for preview using any method you -choose, as long as you can wrap it in a function that meets these -criteria. - -The second element must be a dictionary of keyword arguments to pass -to the filter function. The dictionary may be empty. - -For example, if you have python-markdown installed, you could use it -like this:: - - MARKITUP_PREVIEW_FILTER = ('markdown.markdown', {'safe_mode': True}) - -Alternatively, you could use the "textile" filter provided by Django -like this:: - - MARKITUP_PREVIEW_FILTER = ('django.contrib.markup.templatetags.markup.textile', {}) - -(The textile filter function doesn't accept keyword arguments, so the -kwargs dictionary must be empty in this case.) - -**Note:** If you use your own custom MarkItUp! set, be sure to set the - ``previewParserPath`` option to ``'/markitup/preview/'``. - - -Other settings -============== - -MarkItUp! requires the jQuery Javascript library. By default, -django-markitup links to the most recent minor version of jQuery 1.3 -available at ajax.googleapis.com (via the URL -``http://ajax.googleapis.com/ajax/libs/jquery/1.3/jquery.min.js``). -If you wish to use a different version of jQuery, or host it yourself, -set the JQUERY_URL setting. For example:: - - JQUERY_URL = 'jquery.min.js' - -This will use the jQuery available at MEDIA_URL/jquery.min.js. diff --git a/setup.py b/setup.py index c257ca0..4f24e4f 100644 --- a/setup.py +++ b/setup.py @@ -2,8 +2,9 @@ from setuptools import setup, find_packages setup( name='django-markitup', - version='0.2.2dev', + version='0.2.2', description='Django integration with the MarkItUp universal markup editor', + long_description=open('README.txt').read(), author='Carl Meyer', author_email='carl@dirtcircle.com', url='http://launchpad.net/django-markitup',