Commits

Anonymous committed 1fbc932

first proposal for readme

  • Participants

Comments (0)

Files changed (7)

+Development setup
+=================
+
+To create a buildout,
+
+  $ python bootstrap.py
+  $ bin/buildout
+
+Release HOWTO
+=============
+
+To make a release, 
+
+  1) Update release date/version in NEWS.txt and setup.py
+  2) Run 'python setup.py sdist'
+  3) Test the generated source distribution in dist/
+  4) Upload to PyPI: 'python setup.py sdist register upload'
+  5) Increase version in setup.py (for next release)
+
+include README.rst
+include NEWS.txt
+.. This is your project NEWS file which will contain the release notes.
+.. Example: http://www.python.org/download/releases/2.6/NEWS.txt
+.. The content of this file, along with README.rst, will appear in your
+.. project's PyPI page.
+
+News
+====
+
+0.2a1
+-----
+
+*Release date: UNRELEASED*
+
+* Example news entry for the in-development version
+
+
+0.1
+---
+
+*Release date: 15-Mar-2010*
+
+* Example news entry for a released version
+
+django-simplesearch
+===================
+
+This is a simple search app. It's not a goal to make another google or to manage gazillion of documents in the database, but to have a easy to configure and intuitive to use search app for your django project.
+
+Installation
+------------
+
+Install *django-simplesearch* via `pip`::
+
+	$ pip install django-simplesearch
+	
+Configuration
+-------------
+
+Add the sub-apps from *simplesearch* to your *INSTALLED_APPS* in the *settings.py*::
+
+	INSTALLED_APPS = (
+	# ...
+	'simplesearch.index',
+	'simplesearch.query',
+	# ...
+	)
+	
+If you want to enable the standard search and don't want to use a custom search form, add one line to your *urls.py*::
+
+	urlpattern = pattern('',
+	# ...
+	include(r'^search', include('simplesearch.query.urls')),
+	# ...
+	)
+	
+Indexing
+~~~~~~~~
+
+ Hence you use the out of the box indexer, I will explain now how to fed it. Maybe you want to do:
+ 
+ * Easily fead all instances of a model.
+ * Exclude some fields.
+ * Exclude some instances.
+  
+ In your root-urlconf, activate the indexer::
+  
+  	from simplesearch import index
+  	index.autodiscover()
+  
+ In the file you've specified in the INDEXER_CONF variable in your *settings.py* (the default is *indexer*), you have to initialize the index::
+ 
+ 	from simplesearch import index
+ 
+ The easiest way to build the index is to add the whole project::
+ 
+ 	index.index_project()
+ 	
+ What happens now? All models from all installed apps are examined, so that all indexable fields are used for the index. There's no single field or model-instance which is excluded of the search results. 
+ 
+ For example TextFields are indexable, BooleanFields are not.
+ 
+ The more fine granular step is do index a whole app::
+ 
+ 	index.index_app('django.contrib.comments') 
+ 	
+ or just::
+ 
+ 	index.index_app('comments')
+ 	
+ In both cases, all models are indexed. Even more fine granular is to index a very model of an app. Therefore just write::
+ 
+ 	from myapp.models import MyModel
+ 	index.index_model(MyModel)
+ 	
+ All indexable fields of `MyModel` are indexed. Even yet more fine granular is to index only a subset of fields::
+ 
+ 	from myapp.models import MyModel
+ 	index.index_model(MyModel, 'my_text_field', 'my_char_field')
+ 
+ After all, you can tell the index **not** to index something::
+ 
+ 	index.index_app('django.contrib.comments', exlude=True)
+ 	
+ or a model::
+ 
+ 	index.index_model(MyModel, exclude=True)
+ 	
+ or some fields::
+ 
+ 	index.index_model(MyModel, 'my_text_field', exclude=True)
+ 	
+ **Note: Not indexing something outweighs indexing something!**
+ 
+ For example, if you want to index a whole project, but don't want to index comments of the django.contrib.comments-app, just do::
+ 
+ 	index.index_project()
+ 	index.index_app('django.contrib.comments', exclude=True)
+ 
+ Search results
+ ~~~~~~~~~~~~~~
+ 
+ The search result are delivered by the `query` part of simplesearch. I will think about this, when the index is finished.
+ 
+ 	

File bootstrap.py

+##############################################################################
+#
+# Copyright (c) 2006 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""Bootstrap a buildout-based project
+
+Simply run this script in a directory containing a buildout.cfg.
+The script accepts buildout command-line options, so you can
+use the -c option to specify an alternate configuration file.
+
+$Id: bootstrap.py 102545 2009-08-06 14:49:47Z chrisw $
+"""
+
+import os, shutil, sys, tempfile, urllib2
+from optparse import OptionParser
+
+tmpeggs = tempfile.mkdtemp()
+
+is_jython = sys.platform.startswith('java')
+
+# parsing arguments
+parser = OptionParser()
+parser.add_option("-v", "--version", dest="version",
+                          help="use a specific zc.buildout version")
+parser.add_option("-d", "--distribute",
+                   action="store_true", dest="distribute", default=True,
+                   help="Use Disribute rather than Setuptools.")
+
+options, args = parser.parse_args()
+
+if options.version is not None:
+    VERSION = '==%s' % options.version
+else:
+    VERSION = ''
+
+USE_DISTRIBUTE = options.distribute
+args = args + ['bootstrap']
+
+to_reload = False
+try:
+    import pkg_resources
+    if not hasattr(pkg_resources, '_distribute'):
+        to_reload = True
+        raise ImportError
+except ImportError:
+    ez = {}
+    if USE_DISTRIBUTE:
+        exec urllib2.urlopen('http://python-distribute.org/distribute_setup.py'
+                         ).read() in ez
+        ez['use_setuptools'](to_dir=tmpeggs, download_delay=0, no_fake=True)
+    else:
+        exec urllib2.urlopen('http://peak.telecommunity.com/dist/ez_setup.py'
+                             ).read() in ez
+        ez['use_setuptools'](to_dir=tmpeggs, download_delay=0)
+
+    if to_reload:
+        reload(pkg_resources)
+    else:
+        import pkg_resources
+
+if sys.platform == 'win32':
+    def quote(c):
+        if ' ' in c:
+            return '"%s"' % c # work around spawn lamosity on windows
+        else:
+            return c
+else:
+    def quote (c):
+        return c
+
+cmd = 'from setuptools.command.easy_install import main; main()'
+ws  = pkg_resources.working_set
+
+if USE_DISTRIBUTE:
+    requirement = 'distribute'
+else:
+    requirement = 'setuptools'
+
+if is_jython:
+    import subprocess
+
+    assert subprocess.Popen([sys.executable] + ['-c', quote(cmd), '-mqNxd',
+           quote(tmpeggs), 'zc.buildout' + VERSION],
+           env=dict(os.environ,
+               PYTHONPATH=
+               ws.find(pkg_resources.Requirement.parse(requirement)).location
+               ),
+           ).wait() == 0
+
+else:
+    assert os.spawnle(
+        os.P_WAIT, sys.executable, quote (sys.executable),
+        '-c', quote (cmd), '-mqNxd', quote (tmpeggs), 'zc.buildout' + VERSION,
+        dict(os.environ,
+            PYTHONPATH=
+            ws.find(pkg_resources.Requirement.parse(requirement)).location
+            ),
+        ) == 0
+
+ws.add_entry(tmpeggs)
+ws.require('zc.buildout' + VERSION)
+import zc.buildout.buildout
+zc.buildout.buildout.main(args)
+shutil.rmtree(tmpeggs)

File buildout.cfg

+[buildout]
+parts = python scripts
+develop = .
+eggs = django-simplesearch
+
+[python]
+recipe = zc.recipe.egg
+interpreter = python
+eggs = ${buildout:eggs}
+
+[scripts]
+recipe = zc.recipe.egg:scripts
+eggs = ${buildout:eggs}
+from setuptools import setup, find_packages
+import sys, os
+
+here = os.path.abspath(os.path.dirname(__file__))
+README = open(os.path.join(here, 'README.rst')).read()
+NEWS = open(os.path.join(here, 'NEWS.txt')).read()
+
+
+version = '0.1'
+
+install_requires = [
+    # List your project dependencies here.
+    # For more details, see:
+    # http://packages.python.org/distribute/setuptools.html#declaring-dependencies
+]
+
+
+setup(name='django-simplesearch',
+    version=version,
+    description="A simple search app for django.",
+    long_description=README + '\n\n' + NEWS,
+    classifiers=[
+      # Get strings from http://pypi.python.org/pypi?%3Aaction=list_classifiers
+    ],
+    keywords='django search',
+    author='Julian Moritz',
+    author_email='',
+    url='',
+    license='BSD',
+    packages=find_packages('src'),
+    package_dir = {'': 'src'},include_package_data=True,
+    zip_safe=False,
+    install_requires=install_requires,
+    entry_points={
+        'console_scripts':
+            ['django-simplesearch=djangosimplesearch:main']
+    }
+)