Convert documentation to Markdown

The documentation is never going to expand beyond the README and the CHANGELOG so it makes no sense to keep supporting Sphinx based docs and the associated packages and tooling.
StuartMacKay · Oct 23, 2023 · 2f09234 · 2f09234
1 parent 919f26d
commit 2f09234
Show file tree

Hide file tree

Showing 21 changed files with 128 additions and 387 deletions.
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -39,7 +39,3 @@ jobs:
       - name: Tox tests
         run: |
           tox
-
-      - name: Tox doc tests
-        run: |
-          tox -e docs
diff --git a/.readthedocs.yml b/.readthedocs.yml
diff --git a/CHANGELOG.rst → CHANGELOG.md b/CHANGELOG.rst → CHANGELOG.md
@@ -1,27 +1,29 @@
-Changelog
-=========
+# Changelog
 
-Latest
-------
+All notable changes to this project will be documented in this file.
 
-2.0.4 (2022-02-17)
-------------------
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Latest
+
+* Update project layout to match [django-app-template](https://github.com/StuartMacKay/django-app-template).
+* Converted documentation to Markdown.
+
+## v2.0.4 (2022-02-17)
 
 * Document using media files instead of the custom changelist template.
 * Update the supported django versions and tidy up the manifest.
 
-2.0.3 (2022-02-07)
-------------------
+## v2.0.3 (2022-02-07)
 
 * Update css styles for setting filter title and shortcut links.
 
-2.0.2 (2021-12-21)
-------------------
+## v2.0.2 (2021-12-21)
 
 * Fix docs version and release numbers mangled by bump2version.
 
-2.0.1 (2021-12-21)
-------------------
+## v2.0.1 (2021-12-21)
 
 * Updated installation instructions to simply usage.
 * Replaced travis with github actions for testing.
@@ -31,17 +33,14 @@ Latest
 * Split requirements into separate files for docs, tests and development.
 * Added config file for Read the Docs.
 
-v2.0.0 - 2020-09-18
--------------------
+## v2.0.0 - 2020-09-18
 
 * Completely rewritten to use a modern version of Django (2.2+).
 
-v0.1.0 - 2017-08-20
--------------------
+## v0.1.0 - 2017-08-20
 
 * Modernised to support the current version of Django (1.11).
 
-v0.0.1 - 2011-07-28
--------------------
+## v0.0.1 - 2011-07-28
 
 * Initial release
diff --git a/Makefile b/Makefile
@@ -46,7 +46,6 @@ help:
 	@echo "  clean-build          to clean the files and directories generated by previous builds"
 	@echo "  clean-coverage       to clean the test coverage data and reports"
 	@echo "  clean-mypy           to clean the directory generated by mypy"
-	@echo "  clean-docs           to clean the generated HTML documentation"
 	@echo "  clean-tests          to clean the directories created during testing"
 	@echo "  clean-venv           to clean the virtualenv"
 	@echo "  clean                to clean everything EXCEPT the virtualenv"
@@ -60,7 +59,6 @@ help:
 	@echo "  tox                  to run the tests for all the supported environments"
 	@echo
 	@echo "  build                to build the package"
-	@echo "  docs                 to build the HTML documentation"
 	@echo
 	@echo "  major                to update the version number for a major release, e.g. 2.1 to 3.0"
 	@echo "  minor                to update the version number for a minor release, e.g. 2.1 to 2.2"
@@ -84,10 +82,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
@@ -103,7 +97,7 @@ clean-coverage:
 	rm -rf coverage
 
 .PHONY: clean
-clean: clean-build clean-coverage clean-docs clean-mypy clean-tests
+clean: clean-build clean-coverage clean-mypy clean-tests
 
 # ##############
 #   Virtualenv
@@ -119,17 +113,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
@@ -139,7 +130,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
@@ -182,15 +172,6 @@ tests:
 .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
@@ -0,0 +1,104 @@
+# Django DateRange Filterspec
+
+Adds a form with AdminDateWidgets that can be used to select a range of
+dates for filtering the list of records displayed in an admin Changelist.
+
+![Filter list](https://raw.githubusercontent.com/StuartMacKay/django-daterange-filterspec/master/docs/images/screenshot.png)
+
+The `From date` selects records with a date equal or greater than the 
+specified date. The `To date` selects record up to, but not including
+the specified date. Either field is optional. If you only enter a date 
+in the `From date` field then all records from that date onwards will be
+displayed. Similarly if you only enter a date in the `To date` field then
+only records before that date will be displayed.
+
+## Quick start
+
+Install the package from PyPI:
+
+```shell
+pip install django-daterange-filterspec
+```
+
+The package includes a template, which loads Django's calendar widget
+and date shortcuts. Add the package to the INSTALLED_APPS setting so the
+template loader can find it:
+
+```python
+INSTALLED_APPS = (
+    ...
+    "daterange.apps.DateRangeFilterConfig",
+    ...
+)
+```
+
+In your ModelAdmin, set the template used for the changelist to the one
+provided by the package. Then, for each field you want to filter on
+create a tuple with the name of the field and the `DateRangeFilter`
+filter class:
+
+```python
+from django.contrib import admin
+
+from daterange.filters import DateRangeFilter
+
+from .models import Article
+
+
+@admin.register(Article)
+class ArticleAdmin(admin.ModelAdmin):
+
+    list_display = ["title", "slug", "published"]
+    list_filter = [("published", DateRangeFilter)]
+    ordering = ["-created"]
+
+    change_list_template = "admin/daterange/change_list.html"
+```
+
+If you're already using a customised changelist template, you can add the necessary
+css and javascript files to the Media class for the ModelAdmin:
+
+```python
+@admin.register(Article)
+class ArticleAdmin(admin.ModelAdmin):
+
+    ...
+
+    class Media:
+        css = {"all": ("admin/css/forms.css", "css/admin/daterange.css")}
+        js = ("admin/js/calendar.js", "js/admin/DateRangeShortcuts.js")
+```
+
+Now, go forth and filter!
+
+## Demo
+
+If you check out the project from the repository there is a fully functioning
+Django site that you can use to see the filter in action.
+
+```shell
+git clone [email protected]:StuartMacKay/django-daterange-filterspec.git
+cd django-daterange-filterspec
+```
+
+Create the virtual environment:
+
+```shell
+python -m venv venv
+source venv/bin/activate
+
+pip install --upgrade pip setuptools wheel
+pip install pip-tools
+pip-sync requirements/dev.txt
+```
+
+Run the demo:
+
+```shell
+python manage.py migrate
+python manage.py createsuperuser
+python manage.py runserver
+```
+
+Now log into the Django Admin. In the Demo section, add some Articles
+for different dates and filter away.
diff --git a/README.rst b/README.rst
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/changelog.rst b/docs/changelog.rst