Improvement of docs

Author: Jens Kadenbach

README.md

@@ -0,0 +1,60 @@
+About Pypo
+==========
+
+Pypo is a self hosted bookmarking service like `Pocket`_. This is a very
+early alpha. There will be an android application, bookmarklets and
+possibly a firefox extension to add, search and view the bookmarks.
+
+It's main components are built with:
+
+-  Python
+-  Postgresql
+-  Django
+-  readability-lxml
+-  Whoosh
+-  django-haystack
+-  django-taggit
+-  tld
+-  South
+-  requests
+-  djangorestframework
+
+Features
+--------
+
+-  Adding links to the users own link list
+-  Fetch summary and title from those links
+-  Add tags
+-  Search by title, url and tags
+
+Installation
+------------
+
+1. Create a virtualenv and
+
+   pip install -r requirements.txt
+
+2. Setup a postgresql db
+3. You can overwrite the default settings by creating a
+   settings\_local.py next to pypo/settings.py . Do not directly edit
+   the settings.py.
+4. Setup the database
+
+   ./manage.py syncdb ./manage.py migrate
+
+5. Add a superuser
+
+   ./manage.py createsuperuser
+
+6. Host the application, see `Deploying Django with WSGI`_
+7. Create normal users with the admin interface /admin
+8. That should do it.
+
+License
+-------
+
+This project is licensed under the terms of the Apache License version
+2. See COPYING.txt for details.
+
+.. _Pocket: http://www.getpocket.com
+.. _Deploying Django with WSGI: https://docs.djangoproject.com/en/1.6/howto/deployment/wsgi/

README.rst

@@ -6,15 +6,12 @@
 Welcome to pypo's documentation!
 ================================
 
-Contents:
-
 .. toctree::
    :maxdepth: 2
 
-This is just a stub.
-
-.. autoclass:: readme.models.Item
+   readme_module
 
+.. include:: ../README.rst
 
 
 Indices and tables

doc/index.rst

@@ -0,0 +1,16 @@
+Readme Module
+=============
+
+Everything except for configuration.
+
+Models
+------
+
+.. automodule:: readme.models
+    :members:
+
+Scrapers
+--------
+
+.. automodule:: readme.scrapers
+    :members:

doc/readme_module.rst

@@ -16,19 +16,35 @@
 
 
 class Item(models.Model):
+    """
+    Entry in the read-it-later-list
+
+    """
+    #:param url Page url
     url = models.URLField(max_length=2000)
+    #:param title Page title
     title = models.TextField()
+    #:param created Creating date of the item
     created = models.DateTimeField(auto_now_add=True)
+    #:param owner Owning user
     owner = models.ForeignKey(User)
+    #:param readable_article Processed content of the url
     readable_article = models.TextField(null=True)
+    #:param tags User assigned tags
     tags = TaggableManager(blank=True)
 
     @property
     def summary(self):
+        '''
+        Shortened artile
+        '''
         return strip_tags(self.readable_article)[:300]
 
     @property
     def domain(self):
+        """
+        Domain of the url
+        """
         return get_tld(self.url.encode('utf-8'), fail_silently=True)
 
     def get_absolute_url(self):
@@ -38,6 +54,10 @@ def get_delete_url(self):
         return reverse('item_delete', args=[str(self.id)])
 
     def fetch_article(self):
+        """
+        Fetches a title and a readable_article for the current url.
+        It uses the scrapers module for this and only downloads the content.
+        """
         url = self.url
         try:
             req = requests.get(url, stream=True)

readme/models.py

@@ -4,6 +4,10 @@
 
 
 class ParserException(Exception):
+    '''
+    Generic exception for parsers/scrapers.
+    Indicates that a scraper cannot succeed.
+    '''
     pass
 
 
@@ -34,6 +38,7 @@ def parse(item, content_type, text=None, content=None):
 def domain_parser(domain):
     """
     Decorator to register a domain specific parser
+
     :param domain: String
     :return: function
     """
@@ -45,7 +50,9 @@ def decorator(func):
 
 def parse_web_page(text):
     """
-    Generic wep page parser with readability
+    Generic wep page parser with readability.
+    Used as a fallback.
+
     :param text: unicode text
     :return: title, article
     :raise ParserException:
@@ -63,6 +70,15 @@ def parse_web_page(text):
 @domain_parser('github.com')
 @domain_parser('bitbucket.org')
 def parse_github(item, content_type, text):
+    """
+    Reads the readme of a repo if it can find one.
+
+    :param item:  ignored
+    :param content_type: ignored
+    :param text: unicode text
+    :return: title, article
+    :raise ParserException: raised of no readme is found
+    """
     if text is None:
         raise ParserException('Could not decode content')
     doc = document_fromstring(text)