From ca433cd87224a419a19f38e22ad4bb31ded63a47 Mon Sep 17 00:00:00 2001
From: Stuart MacKay <smackay@flagstonesoftware.com>
Date: Fri, 29 Sep 2023 15:02:20 +0100
Subject: [PATCH] Update introductory documentation

---
 README.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 84 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 0b91714..e22650b 100644
--- a/README.md
+++ b/README.md
@@ -5,22 +5,97 @@
 
 Django Feeds is an aggregator for RSS and Atom feeds.
 
+The app provides the following models. A Source represents any web site that 
+syndicates their content. A Source can have one or more Feeds. That way you
+can selectively load feeds from a newspaper site. Feeds are loaded automatically
+using Celery. However, you can also load feeds manually in the Django Admin
+views provided. There is a default schedule, currently set to load enabled 
+Feeds every hour. You can also set the schedule individual Feeds. An Article
+is created for every new entry from the Feed. Existing Articles are updated,
+but not all fields are tracked. Authors and Tags are not synced. That allows
+you, for example, to set the correct Author of a guest post or add new Tags
+without losing the changes the next time the Feed is loaded.
+
 ## Features
 
+* Uses [feedparser](https://github.com/kurtmckee/feedparser) to load RSS or Atom feeds.
+
+* Uses [django-tagulous](https://github.com/radiac/django-tagulous) for defining hierarchical categories that describes an Article, e.g. 'media/video', 'label/updated'.
+
+* Source and Article support a JSON data field to extend the models, making it easy, for example to load and store OpenGraph data to add thumbnail images.
+
+* An Alias model allows you to map (Wordpress) usernames to real name.
+
+* The app contains Admin views, filters and actions for managing your feeds.
+
 ## Quick Start
 
+Download and install the app:
+
+```pip istall django-rss-feeds```
+
+Add the app to Django:
+
+```python
+INSTALLED_APPS = [
+    ...,
+    "tagulous",
+    "feeds.apps.Config",
+]
+```
+
+Run the migrations:
+
+```python manage.py migrate```
+
+Now log into the Django Admin. In the Feeds section, add a Source and a Feed for that Source.
+Try, https://news.ycombinator.com/rss. Now in the Feed changelist, select the Feed you just 
+added and run the 'Load selected feeds' action. Voila, you now have a set of Articles created
+from the feed.
+
 ## Demo
 
 If you clone or download the [django-feeds](https://github.com/StuartMacKay/django-feeds) 
-repository there is a demonstration application that lets you see how it 
-all works.
+repository there is a demonstration Django application, with celery, that lets 
+you see how it all works. The demo site aggregates the feeds and publishes the 
+Articles , grouped by date, with each page showing the Articles for the past 7
+days. Links on each entry allow you navigate to ListViews for each Source, 
+Author or Tag.
 
 ```shell
 git clone git@github.com:StuartMacKay/django-feeds.git
-cd django-feeds
-make install
-make demo
-``` 
-It's a standard django project so if you don't have `make` available
-then just look at the [Makefile](Makefile) and run the commands from
-the various targets.
+docker-compose up
+```
+
+Next run a shell on the web service, so you can create an admin account, log in 
+and add a Source and a Feed.
+
+```shell
+docker-compose exec web bash
+./manage.py createsuperuser
+```
+
+## Settings
+
+`FEEDS_TASK_SCHEDULE`, default "0 * * * *". A crontab string that set when
+a Celery task runs to check whether any Feeds are scheduled to load.
+
+`FEEDS_LOAD_SCHEDULE`, default "0 * * * *". A crontab string that sets when 
+Feeds is scheduled to be loaded. This can be overridden on Feeds individually.
+
+`FEEDS_USER_AGENT`, the User-Agent string that identifies who is requesting the 
+feed. Some sites won't work without this set. In any case it's always good 
+manners to identify yourself.
+
+`FEEDS_NORMALIZE_TITLES`, default True. Tidy up titles to remove surrounding quotes,
+remove trailing periods, etc. That way titles from different Feeds have the same style.
+
+`FEEDS_TRUNCATE_TITLES`, default None. Limit the length of titles. Some titles are 
+mini-posts all by themselves so you can used this to truncate them to a given number 
+of characters.
+
+`FEEDS_FILTER_TAGS`, default {"uncategorized": None}. Use this to rename or delete
+tags from the Feed. The default allows you to remove the default "Uncategorized" tag
+that often appears in Wordpress feeds. There is a `load_tags` flag on Feed that controls 
+whether tags are added to Articles. That allows you to selectively load the tags from
+conscientious blogs and skip the lazy one.