Attempting to placate github's arcane symlinked-readme rules.

dsc · Aug 29, 2011 · 040f645 · 040f645
1 parent 2b7d164
commit 040f645
Show file tree

Hide file tree

Showing 3 changed files with 72 additions and 21 deletions.
diff --git a/README b/README
@@ -1 +1 @@
-README.rst
+README.md
diff --git a/README.md b/README.md
@@ -0,0 +1,52 @@
+# PyQuery: a jQuery-like library for Python
+
+PyQuery allows you to make [jQuery](http://jquery.com)-style CSS-selector queries on XML/HTML
+documents. The API is intended to match [jQuery's API](http://api.jquery.com) whenever possible,
+though it has been made more Pythonic where appropriate.
+
+This [project](https://github.com/dsc/pyquery) is a fork of the [original](http://www.bitbucket.org/olauzanne/pyquery) 
+PyQuery developed by Olivier Lauzanne in 2008; it is maintained by [David Schoonover](mailto:dsc@less.ly). Feedback and bug
+reports are both very welcome over on [github](https://github.com/dsc/pyquery/issues).
+
+
+## Quickstart
+
+You can use the PyQuery class to load an xml document from a string, a lxml
+document, from a file or from an url:
+
+    >>> from pyquery import PyQuery as pq
+    >>> from lxml import etree
+    >>> import urllib
+    >>> d = pq("<html></html>")
+    >>> d = pq(etree.fromstring("<html></html>"))
+    >>> d = pq(url='http://google.com/')
+    >>> # d = pq(url='http://google.com/', opener=lambda url: urllib.urlopen(url).read())
+    >>> d = pq(filename=path_to_html_file)
+
+Now `d` is like the `$` object in jQuery:
+
+    >>> d("#hello")
+    [<p#hello.hello>]
+    >>> p = d("#hello")
+    >>> print(p.html())
+    Hello world !
+    >>> p.html("you know <a href='http://python.org/'>Python</a> rocks")
+    [<p#hello.hello>]
+    >>> print(p.html())
+    you know <a href="http://python.org/">Python</a> rocks
+    >>> print(p.text())
+    you know Python rocks
+
+You can use some of the pseudo classes that are available in jQuery but that
+are not standard in css such as `:first`, `:last`, `:even`, `:odd`, `:eq`, 
+`:lt`, `:gt`, `:checked`, `:selected`, and `:file`.
+
+    >>> d('p:first')
+    [<p#hello.hello>]
+
+
+##  Notes
+
+ * PyQuery uses lxml for fast XML and HTML manipulation.
+ * This is not a library to produce or interact with JavaScript code. If
+that's what you need, check out
diff --git a/README.rst b/README.rst
@@ -1,28 +1,21 @@
-pyquery: a jQuery-like library for Python
+PyQuery: a jQuery-like library for Python
 =========================================
 
-pyquery allows you to make jQuery queries on html and xml documents.
+PyQuery allows you to make `jQuery`_-style CSS-selector queries on XML/HTML documents.
-The API is as much as possible the similar to jQuery. pyquery uses lxml for fast
+The API is intended to match `jQuery's API`_ whenever possible, 
-xml and html manipulation.
+though it has been made more Pythonic where appropriate.
 
-This is not (or at least not yet) a library to produce or interact with
+This `project`_ is a fork of the `original`_ PyQuery developed by Olivier Lauzanne in 2008;
-javascript code. I just liked the jQuery API and I missed it in python so I
+it is maintained by `David Schoonover`_. Feedback and bug reports are 
-told myself "Hey let's make jQuery in python". This is the result.
+both very welcome over on `github`_.
 
-It can be used for many purposes, one idea that I might try in the future is to
+.. _jQuery: http://jquery.com
-use it for templating with pure http templates that you modify using pyquery.
+.. _jQuery's API: http://api.jquery.com
-I can also be used for web scrapping or for theming applications with
+.. _project: https://github.com/dsc/pyquery
-`Deliverance`_.
+.. _original: http://www.bitbucket.org/olauzanne/pyquery
+.. _David Schoonover: mailto:dsc@less.ly
+.. _github: https://github.com/dsc/pyquery/issues
 
-The `project`_ is being actively developped on a mercurial repository on
-Bitbucket. I have the policy of giving push access to anyone who wants it
-and then to review what he does. So if you want to contribute just email me.
-
-Please report bugs on `github <https://github.com/dsc/pyquery/issues`_.
-
-.. _fork: https://github.com/dsc/pyquery
-.. _deliverance: http://www.gawel.org/weblog/en/2008/12/skinning-with-pyquery-and-deliverance
-.. _project: http://www.bitbucket.org/olauzanne/pyquery/
 
 Quickstart
 ==========
@@ -60,3 +53,9 @@ are not standard in css such as :first :last :even :odd :eq :lt :gt :checked
     >>> d('p:first')
     [<p#hello.hello>]
 
+Notes
+=====
+
+ * PyQuery uses lxml for fast XML and HTML manipulation.
+ * This is not a library to produce or interact with JavaScript code. If that's what you need, check out 
+