Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Sphinx based documentation #178

Merged
merged 4 commits into from
Apr 4, 2022
+858 −179
Merged

Sphinx based documentation #178

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7564b78
Added docs extracted from the README.md
valberg Apr 1, 2022
a0998b4
Add whole changelog. Add contributing.
valberg Apr 4, 2022
4c5aa6c
Fix doc title.
valberg Apr 4, 2022
63b0122
Fetch project information from pyproject.toml.
valberg Apr 4, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,3 +11,4 @@ git-push.bat
.python-version
.coverage
/.idea/
docs/_build/
181 changes: 3 additions & 178 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
valberg marked this conversation as resolved.
Show resolved Hide resolved

### 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/
20 changes: 20 additions & 0 deletions docs/Makefile
View file
Open in desktop
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)
Loading