-
-
Notifications
You must be signed in to change notification settings - Fork 166
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #178 from valberg/docs
Sphinx based documentation
- Loading branch information
Showing
12 changed files
with
858 additions
and
179 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -11,3 +11,4 @@ git-push.bat | |
| .python-version | ||
| .coverage | ||
| /.idea/ | ||
| docs/_build/ | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -8,187 +8,12 @@ | |
|
|
||
| ## About | ||
|
|
||
| Generic invitations solution with adaptable backend and support for django-allauth. All emails and messages are fully customisable. | ||
|
|
||
| Originally written as an invitations solution for the excellent [django-allauth](https://github.com/pennersr/django-allauth), this app has been refactored to remove the allauth dependency whilst retaining 100% backwards compatibility. | ||
| Generic invitations solution with adaptable backend and support for django-allauth. | ||
|
|
||
| ## Contributing | ||
|
|
||
| As we are members of a [JazzBand project](https://jazzband.co/projects), `django-invitations` contributors should adhere to the [Contributor Code of Conduct](https://jazzband.co/about/conduct). | ||
|
|
||
| ## Installation | ||
|
|
||
| 1. Install with pip | ||
| ``` | ||
| pip install django-invitations | ||
| ``` | ||
|
|
||
| 2. Add django.contrib.sites" and 'invitations to INSTALLED_APPS | ||
|
|
||
| ``` | ||
| INSTALLED_APPS = [ | ||
| ... | ||
| "django.contrib.sites", | ||
| "invitations", | ||
| ... | ||
| ] | ||
| ``` | ||
|
|
||
| 2. Make sure you have SITE_ID defined in settings | ||
| ``` | ||
| SITE_ID = 1 | ||
| ``` | ||
|
|
||
| 3. Append to urls.py | ||
|
|
||
| ``` | ||
| urlpatterns = [ | ||
| ... | ||
| path("invitations/", include('invitations.urls', namespace='invitations')), | ||
| ... | ||
| ] | ||
| ``` | ||
|
|
||
| 4. Run migrations | ||
|
|
||
| ``` | ||
| python manage.py migrate | ||
| ``` | ||
|
|
||
| ## Usage | ||
|
|
||
| There are two primary ways to use `django-invitations` described below. | ||
|
|
||
| Generic Invitation flow: | ||
|
|
||
| * Priviledged user invites prospective user by email (via either Django admin, form post, JSON post or programmatically) | ||
| * User receives invitation email with confirmation link | ||
| * User clicks link and is redirected to a preconfigured url (default is accounts/signup) | ||
|
|
||
| Allauth Invitation flow: | ||
|
|
||
| * As above but.. | ||
| * User clicks link, their email is confirmed and they are redirected to signup | ||
| * The signup URL has the email prefilled and upon signing up the user is logged into the site | ||
|
|
||
| Further details can be found in the following sections. | ||
|
|
||
| ### Allauth Integration | ||
|
|
||
| As above but note that invitations must come after allauth in the INSTALLED_APPS | ||
|
|
||
| ``` | ||
| # Add to settings.py | ||
| ACCOUNT_ADAPTER = 'invitations.models.InvitationsAdapter' | ||
| ``` | ||
|
|
||
| ### Sending Invites | ||
|
|
||
| First import the model: | ||
|
|
||
| ``` | ||
| from invitations.utils import get_invitation_model | ||
| ``` | ||
|
|
||
| Make an instance of the model: | ||
|
|
||
| ``` | ||
| Invitation = get_invitation_model() | ||
| ``` | ||
|
|
||
| Then finally pass the recipient to the model and send. | ||
|
|
||
| ``` | ||
| # inviter argument is optional | ||
| invite = Invitation.create('[email protected]', inviter=request.user) | ||
| invite.send_invitation(request) | ||
| ``` | ||
|
|
||
| To send invites via django admin, just add an invite and save. | ||
|
|
||
|
|
||
| ### Bulk Invites | ||
|
|
||
| Bulk invites are supported via JSON. Post a list of comma separated emails to the dedicated URL and Invitations will return a data object containing a list of valid and invalid invitations. | ||
|
|
||
|
|
||
| ### Testing | ||
|
|
||
| `python manage.py test` or `tox` | ||
|
|
||
| ### Additional Configuration | ||
|
|
||
| * `INVITATIONS_INVITATION_EXPIRY` (default=`3`) | ||
|
|
||
| Integer. How many days before the invitation expires. | ||
|
|
||
| * `INVITATIONS_INVITATION_ONLY` (default=`False`) | ||
|
|
||
| Boolean. If the site is invite only, or open to all (only relevant when using allauth). | ||
|
|
||
| * `INVITATIONS_CONFIRM_INVITE_ON_GET` (default=`True`) | ||
|
|
||
| Boolean. If confirmations can be accepted via a `GET` request. | ||
|
|
||
| * `INVITATIONS_ACCEPT_INVITE_AFTER_SIGNUP` (default=`False`) | ||
|
|
||
| Boolean. If `True`, invitations will be accepted after users finish signup. | ||
| If `False`, invitations will be accepted right after the invitation link is clicked. | ||
| Note that this only works with Allauth for now, which means `ACCOUNT_ADAPTER` has to be | ||
| `'invitations.models.InvitationsAdapter'`. | ||
|
|
||
| * `INVITATIONS_GONE_ON_ACCEPT_ERROR` (default=`True`) | ||
|
|
||
| Boolean. If `True`, return an HTTP 410 GONE response if the invitation key | ||
| is invalid, or the invitation is expired or previously accepted when | ||
| accepting an invite. If `False`, display an error message and redirect on | ||
| errors: | ||
|
|
||
| * Redirects to `INVITATIONS_SIGNUP_REDIRECT` on an expired key | ||
| * Otherwise, redirects to `INVITATIONS_LOGIN_REDIRECT` on other errors. | ||
|
|
||
| * `INVITATIONS_ALLOW_JSON_INVITES` (default=`False`) | ||
|
|
||
| Expose a URL for authenticated posting of invitees | ||
|
|
||
| * `INVITATIONS_SIGNUP_REDIRECT` (default=`'account_signup'`) | ||
|
|
||
| URL name of your signup URL. | ||
|
|
||
| * `INVITATIONS_LOGIN_REDIRECT` (default=`LOGIN_URL` from Django settings) | ||
|
|
||
| URL name of your login URL. | ||
|
|
||
| * `INVITATIONS_ADAPTER` (default=`'invitations.adapters.BaseInvitationsAdapter'`) | ||
|
|
||
| Used for custom integrations. Set this to `ACCOUNT_ADAPTER` if using django-allauth. | ||
|
|
||
| * `INVITATIONS_EMAIL_MAX_LENGTH` (default=`254`) | ||
|
|
||
| If set to `None` (the default), invitation email max length will be set up to 254. Set this to an integer value to set up a custome email max length value. | ||
|
|
||
| * `INVITATIONS_EMAIL_SUBJECT_PREFIX` (default=`None`) | ||
|
|
||
| If set to `None` (the default), invitation email subjects will be prefixed with the name of the current Site in brackets (such as `[example.com]`). Set this to a string to for a custom email subject prefix, or an empty string for no prefix. | ||
|
|
||
| * `INVITATIONS_INVITATION_MODEL` (default=`invitations.Invitation`) | ||
|
|
||
| App registry path of the invitation model used in the current project, for customization purposes. | ||
|
|
||
| * `CONFIRMATION_URL_NAME` (default=`invitations:accept-invite`) | ||
|
|
||
| String. Invitation confirmation URL | ||
|
|
||
| ### Signals | ||
|
|
||
| The following signals are emitted: | ||
|
|
||
| * `invite_url_sent` | ||
| * `invite_accepted` | ||
|
|
||
|
|
||
| ### Management Commands | ||
|
|
||
| Expired and accepted invites can be cleared as so: | ||
| ### Documentation | ||
|
|
||
| `python manage.py clear_expired_invitations` | ||
| Documentation can be found at https://django-invitations.readthedocs.io/ | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| # Minimal makefile for Sphinx documentation | ||
| # | ||
|
|
||
| # You can set these variables from the command line, and also | ||
| # from the environment for the first two. | ||
| SPHINXOPTS ?= "-W" | ||
| 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) |
Oops, something went wrong.