Replace the user manual model with something more practical

The app is relatively simple so there is little need for a separate user manual hosted on yet another site. Instead the code is considered the source of authority and documentation is added to support the code. For longer form items the Sphinx-based manual will be replaced by individual how-tos and examples written in Markdown. The goal is to have simpler, more accessible, easier to write, easier to maintain docs rather than have to slog through creating another version of War and Peace which nobody reads.
StuartMacKay · Sep 30, 2023 · 209d472 · 209d472
1 parent 5717a52
commit 209d472
Show file tree

Hide file tree

Showing 18 changed files with 60 additions and 360 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
diff --git a/Makefile b/Makefile
@@ -53,7 +53,6 @@ help:
 	@echo ""
 	@echo "  help                 to show this list"
 	@echo "  clean-build          to clean the files and directories generated by previous builds"
-	@echo "  clean-docs           to clean the generated HTML documentation"
 	@echo "  clean-tests          to clean the directories created during testing"
 	@echo "  clean-coverage       to clean the test coverage data and reports"
 	@echo "  clean-venv           to clean the virtualenv"
@@ -62,7 +61,6 @@ help:
 	@echo "  build                to build the package"
 	@echo "  checks               to run quality code checks"
 	@echo "  coverage             to measure the test coverage"
-	@echo "  docs                 to build the HTML documentation"
 	@echo "  install              to install the project dependencies in the virtualenv"
 	@echo "  major                to update the version number for a major release, e.g. 2.1 to 3.0"
 	@echo "  messages             to run the makemessages and compilemessages management commands"
@@ -93,10 +91,6 @@ clean-build:
 	rm -rf build
 	rm -rf src/*.egg-info
 
-.PHONY: clean-docs
-clean-docs:
-	cd docs && make clean
-
 .PHONY: clean-tests
 clean-tests:
 	rm -rf .tox
@@ -112,7 +106,7 @@ clean-coverage:
 	rm -rf coverage
 
 .PHONY: clean
-clean: clean-venv clean-build clean-tests clean-mypy clean-coverage clean-docs
+clean: clean-venv clean-build clean-tests clean-mypy clean-coverage
 
 # ##############
 #   Virtualenv
@@ -135,17 +129,14 @@ $(venv_dir):
 	$(pip) install --upgrade pip setuptools wheel
 	$(pip) install pip-tools
 
-requirements/dev.txt: requirements/dev.in requirements/docs.in requirements/tests.in
+requirements/dev.txt: requirements/dev.in requirements/tests.in
 	$(pip-compile) requirements/dev.in
 
-requirements/docs.txt: requirements/docs.in
-	$(pip-compile) requirements/docs.in
-
-requirements/tests.txt: requirements/docs.in requirements/tests.in
+requirements/tests.txt: requirements/tests.in
 	$(pip-compile) requirements/tests.in
 
 .PHONY: requirements
-requirements: requirements/dev.txt requirements/docs.txt requirements/tests.txt
+requirements: requirements/dev.txt requirements/tests.txt
 
 .PHONY: venv
 venv: $(venv_dir) requirements
@@ -155,7 +146,6 @@ venv: $(venv_dir) requirements
 install: venv
 	$(pip) install --upgrade pip setuptools wheel
 	$(pip) install pip-tools
-	test -f requirements/docs.txt || $(pip-compile) requirements/docs.in
 	test -f requirements/dev.txt || $(pip-compile) requirements/dev.in
 	test -f requirements/tests.txt || $(pip-compile) requirements/tests.in
 	$(pip-sync) requirements/dev.txt
@@ -221,15 +211,6 @@ test:
 .PHONY: tox
 tox: test
 	$(tox)
-	$(tox) -e docs
-
-# ########
-#   Docs
-# ########
-
-.PHONY: docs
-docs:
-	cd docs && make html
 
 # ###########
 #   Release

diff --git a/README.md b/README.md
@@ -72,19 +72,19 @@ from the feed.
 ## Demo
 
 If you clone or download the [django-feeds](https://github.com/StuartMacKay/django-feeds) 
-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.
+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 [email protected]:StuartMacKay/django-feeds.git
 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.
+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
@@ -93,25 +93,38 @@ docker-compose exec web bash
 
 ## 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.
+`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.
+
+## Contributing
+
+This app was written with a single use-case - republishing a list of links 
+to posts from other blogs. It performs that function well, but, as usual,
+there is always room for improvement. Feedback, feature requests, bug 
+reports, improvements to the documentation are all welcome. Read the TODO
+list for things that need work and the HowTos in the docs directory to 
+get started.
diff --git a/TODO.md b/TODO.md
@@ -1,21 +1,17 @@
 # TODO
 
-The code runs and runs well. It has been in production for almost two
-years, so it is rather polished. It was factored out of the 
-[Voices for Independence](https://www.voices.scot) web site with s small
-number of changes and is now being repackaged to make it reusable in other
-projects we have in mind. 
+* Add the HowTo on getting started with development.
 
-* replace the original bootstrap css classes with semantic names, so it 
-  can be restyled easily.
+* Improve type hints.
 
-* move 'business logic' out of the views and out of the querysets into a  
-  services layer - an internal API. That way you're not forced
-  to subclass the views, and you can easily write your own.
+* Django is currently pinned to 3.2 as the autocomplete in the Admin does not 
+  work with the latest version, 4.1.7 (Sept 2023). It is not clear whether this
+  is an error in Django or whether it is a side-effect of using django-tagulous.
 
-* Add more blocks to the templates and create more snippets so again you
-  can easily replace what is provided in the app.
+* The categories template filter, which returns a list of Categories on an Article
+  with a given prefix should either be more robust or intolerant if used incorrectly,
+  i.e. return an empty list or raise an exception. It currently works with Feeds
+  but there is probably no need for it to do.
 
-* Also load the feeds using cron, so you are not forced to use celery.
-
-* Add a REST API - at some point.
+* Read through https://news.ycombinator.com/item?id=35684220 and fix any incompetence
+  on the models.
diff --git a/docs/.gitignore b/docs/.gitignore
diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep
diff --git a/docs/_templates/.gitkeep b/docs/_templates/.gitkeep
diff --git a/docs/conf.py b/docs/conf.py
diff --git a/docs/howtos/get-started-with-development.md b/docs/howtos/get-started-with-development.md
@@ -0,0 +1 @@
+# Get Started With Development
diff --git a/docs/index.rst b/docs/index.rst
diff --git a/docs/make.bat b/docs/make.bat
diff --git a/requirements/dev.in b/requirements/dev.in
@@ -1,5 +1,4 @@
 
--r docs.in
 -r tests.in
 
 # Install the app and dependencies for development. It is done this way