Merge pull request #138 from Gallaecio/documentation-introduction

kmike · web-flow · commit 258107546bae · 2020-05-02T23:54:06.000+05:00
Improve the README.rst file
diff --git a/README.rst b/README.rst
@@ -1,6 +1,6 @@
-===============================
+======
 Parsel
-===============================
+======
 
 .. image:: https://img.shields.io/travis/scrapy/parsel/master.svg
    :target: https://travis-ci.org/scrapy/parsel
@@ -15,22 +15,18 @@ Parsel
    :alt: Coverage report
 
 
-Parsel is a library to extract data from HTML and XML using XPath and CSS selectors
+Parsel is a BSD-licensed Python_ library to extract and remove data from HTML_
+and XML_ using XPath_ and CSS_ selectors, optionally combined with
+`regular expressions`_.
 
-* Free software: BSD license
-* Documentation: https://parsel.readthedocs.org.
+Find the Parsel online documentation at https://parsel.readthedocs.org.
 
-Features
---------
+Example (`open online demo`_):
 
-* Extract text using CSS or XPath selectors
-* Remove elements using CSS or XPath selectors
-* Regular expression helper methods
-
-Example (`open online demo`_)::
+.. code-block:: python
 
     >>> from parsel import Selector
-    >>> sel = Selector(text=u"""<html>
+    >>> selector = Selector(text=u"""<html>
             <body>
                 <h1>Hello, Parsel!</h1>
                 <ul>
@@ -39,16 +35,20 @@ Example (`open online demo`_)::
                 </ul>
             </body>
             </html>""")
-    >>>
-    >>> sel.css('h1::text').get()
+    >>> selector.css('h1::text').get()
     'Hello, Parsel!'
-    >>>
-    >>> sel.css('h1::text').re('\w+')
+    >>> selector.xpath('//h1/text()').re(r'\w+')
     ['Hello', 'Parsel']
-    >>>
-    >>> for e in sel.css('ul > li'):
-    ...     print(e.xpath('.//a/@href').get())
+    >>> for li in selector.css('ul > li'):
+    ...     print(li.xpath('.//@href').get())
     http://example.com
     http://scrapy.org
 
-.. _open online demo: https://colab.research.google.com/drive/149VFa6Px3wg7S3SEnUqk--TyBrKplxCN#forceEdit=true&sandboxMode=true
+
+.. _CSS: https://en.wikipedia.org/wiki/Cascading_Style_Sheets
+.. _HTML: https://en.wikipedia.org/wiki/HTML
+.. _open online demo: https://colab.research.google.com/drive/149VFa6Px3wg7S3SEnUqk--TyBrKplxCN#forceEdit=true&sandboxMode=true
+.. _Python: https://www.python.org/
+.. _regular expressions: https://docs.python.org/library/re.html
+.. _XML: https://en.wikipedia.org/wiki/XML
+.. _XPath: https://en.wikipedia.org/wiki/XPath
