diff --git a/.readthedocs.yml b/.readthedocs.yml deleted file mode 100644 index 88ef114..0000000 --- a/.readthedocs.yml +++ /dev/null @@ -1,11 +0,0 @@ -version: 2 -python: - version: 3.8 - install: - - requirements: requirements/docs.txt - - method: pip - path: . -sphinx: - builder: html - configuration: docs/conf.py - diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index a092e2f..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,15 +0,0 @@ -# Contributing - -## Report Bugs - -## Fix Bugs - -## Implement Features - -## Write Documentation - -## Give Feedback - -## Get Started! - -### Pull Requests diff --git a/Makefile b/Makefile index fe271d0..911b75c 100644 --- 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 index e350e97..816a1a0 100644 --- 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 git@github.com: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 index 484e8f9..6ec90a4 100644 --- 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 deleted file mode 100644 index bf1dffd..0000000 --- a/docs/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -# Ignore the file where the docs are built -_build diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index d4bb2cb..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = . -BUILDDIR = _build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/docs/_templates/.gitkeep b/docs/_templates/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 1874c03..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,59 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath(".")) - - -# -- Project information ----------------------------------------------------- - -project = "Django App Project" -copyright = "2023, Stuart MacKay" -author = "Stuart MacKay" - -version = "0.0" -release = "0.0.0" - - -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named "sphinx.ext.*") or your custom -# ones. - -# napoleon - generate docs from numpy and google docstrings - -extensions = [ - "sphinx.ext.napoleon", -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] - - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "sphinx_rtd_theme" - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ["_static"] diff --git a/docs/howtos/get-started-with-development.md b/docs/howtos/get-started-with-development.md new file mode 100644 index 0000000..853685a --- /dev/null +++ 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 deleted file mode 100644 index 4d5ba8d..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -Welcome to Django App Project's documentation! -============================================== - -Contents: - -.. toctree:: - :maxdepth: 2 - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 922152e..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=. -set BUILDDIR=_build - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/requirements/dev.in b/requirements/dev.in index 445e81d..1ba6022 100644 --- 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 diff --git a/requirements/dev.txt b/requirements/dev.txt index 74c23b1..ab322da 100644 --- a/requirements/dev.txt +++ b/requirements/dev.txt @@ -4,16 +4,12 @@ # # pip-compile requirements/dev.in # --e file:///home/stuart/Development/django-feeds +-e . # via -r requirements/dev.in -alabaster==0.7.13 - # via sphinx amqp==5.1.1 # via kombu asgiref==3.7.2 # via django -babel==2.12.1 - # via sphinx beautifulsoup4==4.12.2 # via bs4 billiard==4.1.0 @@ -82,10 +78,7 @@ django-tagulous==1.3.3 docopt==0.6.2 # via pip-upgrader docutils==0.18.1 - # via - # readme-renderer - # sphinx - # sphinx-rtd-theme + # via readme-renderer exceptiongroup==1.1.3 # via pytest factory-boy==3.3.0 @@ -104,8 +97,6 @@ freezegun==1.2.2 # via pytest-freezegun idna==3.4 # via requests -imagesize==1.4.1 - # via sphinx importlib-metadata==6.8.0 # via # keyring @@ -122,8 +113,6 @@ jeepney==0.8.0 # via # keyring # secretstorage -jinja2==3.1.2 - # via sphinx json-log-formatter==0.5.2 # via -r requirements/dev.in keyring==24.2.0 @@ -132,8 +121,6 @@ kombu==5.3.2 # via celery markdown-it-py==3.0.0 # via rich -markupsafe==2.1.3 - # via jinja2 mccabe==0.7.0 # via flake8 mdurl==0.1.2 @@ -156,7 +143,6 @@ packaging==23.1 # pip-upgrader # pyproject-api # pytest - # sphinx # tox pathspec==0.11.2 # via black @@ -187,7 +173,6 @@ pygments==2.16.1 # via # readme-renderer # rich - # sphinx pyproject-api==1.6.1 # via tox pytest==7.4.2 @@ -221,7 +206,6 @@ requests==2.31.0 # -r requirements/dev.in # pip-upgrader # requests-toolbelt - # sphinx # twine requests-toolbelt==1.0.0 # via twine @@ -235,36 +219,8 @@ sgmllib3k==1.0.0 # via feedparser six==1.16.0 # via python-dateutil -snowballstemmer==2.2.0 - # via sphinx soupsieve==2.5 # via beautifulsoup4 -sphinx==7.2.6 - # via - # -r requirements/docs.in - # sphinx-rtd-theme - # sphinxcontrib-applehelp - # sphinxcontrib-devhelp - # sphinxcontrib-htmlhelp - # sphinxcontrib-jquery - # sphinxcontrib-qthelp - # sphinxcontrib-serializinghtml -sphinx-rtd-theme==1.3.0 - # via -r requirements/docs.in -sphinxcontrib-applehelp==1.0.7 - # via sphinx -sphinxcontrib-devhelp==1.0.5 - # via sphinx -sphinxcontrib-htmlhelp==2.0.4 - # via sphinx -sphinxcontrib-jquery==4.1 - # via sphinx-rtd-theme -sphinxcontrib-jsmath==1.0.1 - # via sphinx -sphinxcontrib-qthelp==1.0.6 - # via sphinx -sphinxcontrib-serializinghtml==1.1.9 - # via sphinx sqlparse==0.4.4 # via # django diff --git a/requirements/docs.in b/requirements/docs.in deleted file mode 100644 index cbf1e36..0000000 --- a/requirements/docs.in +++ /dev/null @@ -1,2 +0,0 @@ -sphinx -sphinx-rtd-theme diff --git a/requirements/docs.txt b/requirements/docs.txt deleted file mode 100644 index 110edaf..0000000 --- a/requirements/docs.txt +++ /dev/null @@ -1,59 +0,0 @@ -# -# This file is autogenerated by pip-compile with python 3.10 -# To update, run: -# -# pip-compile requirements/docs.in -# -alabaster==0.7.13 - # via sphinx -babel==2.12.1 - # via sphinx -certifi==2022.12.7 - # via requests -charset-normalizer==3.1.0 - # via requests -docutils==0.18.1 - # via - # sphinx - # sphinx-rtd-theme -idna==3.4 - # via requests -imagesize==1.4.1 - # via sphinx -jinja2==3.1.2 - # via sphinx -markupsafe==2.1.2 - # via jinja2 -packaging==23.0 - # via sphinx -pygments==2.14.0 - # via sphinx -requests==2.28.2 - # via sphinx -snowballstemmer==2.2.0 - # via sphinx -sphinx==6.1.3 - # via - # -r requirements/docs.in - # sphinx-rtd-theme -sphinx-rtd-theme==1.2.0 - # via -r requirements/docs.in -sphinxcontrib-applehelp==1.0.4 - # via sphinx -sphinxcontrib-devhelp==1.0.2 - # via sphinx -sphinxcontrib-htmlhelp==2.0.1 - # via sphinx -sphinxcontrib-jquery==2.0.0 - # via sphinx-rtd-theme -sphinxcontrib-jsmath==1.0.1 - # via sphinx -sphinxcontrib-qthelp==1.0.3 - # via sphinx -sphinxcontrib-serializinghtml==1.1.5 - # via sphinx -urllib3==1.26.14 - # via requests - -# The following packages are considered to be unsafe in a requirements file: -# setuptools diff --git a/setup.cfg b/setup.cfg index 98379cb..07948fa 100644 --- a/setup.cfg +++ b/setup.cfg @@ -27,26 +27,6 @@ sign_tags = True search = __version__ = "{current_version}" replace = __version__ = "{new_version}" -# The order in which the version numbers in docs/conf.py is important. -# If the release number is not processed first (using the default -# regex for parsing) then you will get the following output: -# -# version = "0.0" -# release = "version = "0.0"" -# -# This has been reported as an issue to bump2version: -# https://github.com/c4urself/bump2version/issues/159 - -[bumpversion:file:docs/conf.py] -search = release = "{current_version}" -replace = release = "{new_version}" - -[bumpversion:file:./docs/conf.py] -parse = (?P\d+)\.(?P\d+) -serialize = {major}.{minor} -search = version = "{current_version}" -replace = version = "{new_version}" - [bumpversion:file:CHANGELOG.md] search = # Latest @@ -66,7 +46,6 @@ replace = version="{new_version}" extend_exclude = */migrations/*, build/, - docs/, venv/ ignore = @@ -130,13 +109,6 @@ directory = coverage envlist = {py38,py310}-django{32,40} - -[testenv:docs] -basepython=python -changedir=docs -deps= -r requirements/docs.txt -commands= - sphinx-build -b html -d {envtmpdir}/doctrees . {envtmpdir}/html [testenv] commands = pytest deps = -r requirements/tests.txt