Documentation pass (#18)

* initial commit

* fix examples, formatting

* formatting

* add documentation

* add api docs

* update README.md

* poetry relock

---------

Co-authored-by: Stefan Pratter <stefan@20c.com>

Author: jason20c

.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: ci
+on:
+  push:
+    branches:
+      - main
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v2
+      - name: Install virtualenv from poetry
+        uses: 20c/workflows/poetry@v1
+      - name: deploy mkdocs gh-pages site
+        run: |
+          poetry run mkdocs gh-deploy --force

README.md

@@ -1,97 +1,18 @@
-
 # django-handleref
 
 [![PyPI](https://img.shields.io/pypi/v/django-handleref.svg?maxAge=3600)](https://pypi.python.org/pypi/django-handleref)
 [![PyPI](https://img.shields.io/pypi/pyversions/django-handleref.svg?maxAge=600)](https://pypi.python.org/pypi/django-handleref)
 [![Tests](https://github.com/20c/django-handleref/workflows/tests/badge.svg)](https://github.com/20c/django-handleref)
 [![Codecov](https://img.shields.io/codecov/c/github/20c/django-handleref/master.svg?maxAge=3600)](https://codecov.io/github/20c/django-handleref)
 
-track when an object was created or changed and allow querying based on time and versioning (w/ django-reversion support)
-
-## HandleRefModel as a base for all your models
-
-    from django.db import models
-    from django_handleref.models import HandleRefModel
-
-    class Test(HandleRefModel):
-        name = models.CharField(max_length=255)
-
-## Querying for modification since
-
-It is now possible for you to see which instances of a model have been created or modified
-since a specific time or version
-
-    import time
-
-    # create instance
-    test = Test.objects.create(name="This is a test")
-
-    # keep track of time, we need this later
-    t = time.time()
-
-    # modifying and saving it
-    test.name = "Changed my mind"
-    test.save()
-
-    # now we can use the handleref manager to retrieve it
-    Test.handleref.since(timestamp=t).count() # 1
-    Test.handleref.since(timestamp=time.time().count() #0
-
-
-## Soft delete
-
-By default all models extending HandleRefModel will softdelete when their delete() method is called.
-Note that this currently wont work for batch deletes - as this does not call the delete() method.
-
-    test = Test.objects.get(id=1)
-    test.delete()
-
-    # querying handleref undeleted will not contain the deleted object
-    Test.handleref.undeleted().filter(id=1).count() #0
-
-    # querying handleref since will not contain the deleted object
-    Test.handleref.since(timestamp=t).filter(id=1).count() #0
-
-    # passing deleted=True to handleref since will contain the deleted object
-    Test.handleref.since(timestamp=t, deleted=True).filter(id=1).count() #1
-
-    # querying using the standard objects manager will contain the deleted object
-    Test.objects.filter(id=1).count() #1
-
-    # You may also still hard-delete by passing hard=True to delete
-    test.delete(hard=True)
-    Test.objects.filter(id=1).count() #0
-
-## Versioning (with django-reversion)
-
-Requires
-
-    django-reversion==1.8.7
-
-When django-reversion is installed all your HandleRefModels will be valid for versioning.
-
-    import reversion
-
-    with reversion.create_revision():
-        obj = Test.objects.create(name="This is a test")
-        obj.save()
-
-        obj.version #1
-
-        obj.name = "Changed my mind"
-        obj.save()
-
-        obj.version #2
-
-    Test.handleref.since(version=1).count() #1
-
+Track when an object was created or changed and allow querying based on time and versioning (w/ `django-reversion` support)
 
 ### License
 
 Copyright 2015-2022 20C, LLC
 
 Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this softare except in compliance with the License.
+you may not use this software except in compliance with the License.
 You may obtain a copy of the License at
 
    http://www.apache.org/licenses/LICENSE-2.0

docs/api/django_handleref.admin.md

@@ -0,0 +1 @@
+{pymdgen:django_handleref.admin}

docs/api/django_handleref.manager.md

@@ -0,0 +1 @@
+{pymdgen:django_handleref.manager}

docs/api/django_handleref.util.md

@@ -0,0 +1 @@
+{pymdgen:django_handleref.util}

docs/api/django_handleref.version.md

@@ -0,0 +1 @@
+{pymdgen:django_handleref.version}

docs/index.md

@@ -0,0 +1 @@
+{!README.md!}

docs/quickstart.md

@@ -0,0 +1,99 @@
+# Quickstart
+
+## Installation
+
+You can install using pip:
+```
+pip install django-handleref
+```
+Optionally install `django-reversions` if you want versioning support.
+```
+pip install django-reversion
+```
+Include them in your `INSTALLED_APPS`
+```python
+    INSTALLED_APPS=[
+        ...
+        "django_handleref",
+        "reversion",
+        ...
+    ],
+```
+
+## HandleRefModel as a base for all your models
+
+    from django.db import models
+    from django_handleref.models import HandleRefModel
+
+    class Test(HandleRefModel):
+        name = models.CharField(max_length=255)
+
+## Querying for modification since
+
+It is now possible for you to see which instances of a model have been created or modified
+since a specific time or version:
+
+    import time
+
+    # create instance
+    test = Test.objects.create(name="This is a test")
+
+    # keep track of time, we need this later
+    t = time.time()
+
+    # modifying and saving it
+    test.name = "Changed my mind"
+    test.save()
+
+    # now we can use the handleref manager to retrieve it
+    Test.handleref.since(timestamp=t).count() #1
+    Test.handleref.since(timestamp=time.time()).count() #0
+
+
+## Soft delete
+
+By default, all models extending `HandleRefModel` will softdelete when their delete() method is called.
+Note that this currently won't work for batch deletes - as this does not call the delete() method.
+
+    test = Test.objects.get(id=1)
+    test.delete()
+
+    # querying handleref undeleted will not contain the deleted object
+    Test.handleref.undeleted().filter(id=1).count() #0
+
+    # querying handleref since will not contain the deleted object
+    Test.handleref.since(timestamp=t).filter(id=1).count() #0
+
+    # passing deleted=True to handleref since will contain the deleted object
+    Test.handleref.since(timestamp=t, deleted=True).filter(id=1).count() #1
+
+    # querying using the standard objects manager will contain the deleted object
+    Test.objects.filter(id=1).count() #1
+
+    # You may also still hard-delete by passing hard=True to delete
+    test.delete(hard=True)
+    Test.objects.filter(id=1).count() #0
+
+## Versioning (with django-reversion)
+
+Requires
+
+    django-reversion>=3.0.0
+
+When `django-reversion` is installed all your `HandleRefModel`s will be valid for versioning.
+
+    import reversion
+
+    with reversion.create_revision():
+        obj = Test.objects.create(name="This is a test")
+        obj.save()
+
+        obj.version #1
+
+        obj.name = "Changed my mind"
+        obj.save()
+
+        obj.version #2
+
+    Test.handleref.since(version=1).count() #1
+

mkdocs.yml

@@ -0,0 +1,18 @@
+site_name: django-handleref
+site_url: https://github.com/20c/django-handleref
+
+theme: readthedocs
+
+nav:
+  - Home: index.md
+  - Quickstart: quickstart.md
+  - API:
+    - django_handleref.admin: api/django_handleref.admin.md
+    - django_handleref.manager: api/django_handleref.manager.md
+    - django_handleref.util: api/django_handleref.util.md
+    - django_handleref.version: api/django_handleref.version.md
+
+markdown_extensions:
+  - markdown_include.include
+  - admonition
+  - pymdgen

poetry.lock

@@ -41,19 +41,19 @@ mypy = ">=0.950"
 pre-commit = "^2.13"
 pyupgrade = "^2.19.4"
 
-# docs
-markdown = "*"
-markdown-include = ">=0.5,<1"
-mkdocs = "^1"
-
 # ctl
 ctl = "^1"
 jinja2 = "^2.11.2"
 tmpl = "^1"
 twine = "^3.3.0"
 
-[tool.poetry.plugins."markdown.extensions"]
-pymdgen = "pymdgen.md:Extension"
+# docs
+markdown-include = ">=0.5"
+mkdocs = "^1.2.3"
+pymdgen = "^1.0.0"
+
+[tool.poetry.extras]
+docs = ["markdown-include", "mkdocs", "pymdgen"]
 
 [build-system]
 requires = ["poetry>=0.12"]