Documentation overhaul

docs/features/core/dashboard.md

@@ -0,0 +1,9 @@
+# Dashboard
+
+The dashboard is the main page of the **Alliance Auth** website and the first page every logged in user will see.
+
+The content of the dashboard is specific to the logged in user. It has a sidebar, which will display the list of apps a user currently as access to based on his permissions. And it also shows which character the user has registered and to which group he belongs.
+
+For admin users the dashboard shows additional technical information about the  AA instance.
+
+![dashboard](/_static/images/features/core/dashboard/dashboard.png)

docs/features/core/groupmanagement.md

@@ -0,0 +1,41 @@
+# Group Management
+
+In order to access group management, users need to be either a superuser, granted the `auth | user | group_management ( Access to add members to groups within the alliance )` permission or a group leader (discussed later).
+
+## Group Requests
+
+When a user joins or leaves a group which is not marked as "Open", their group request will have to be approved manually by a user with the `group_management` permission or by a group leader of the group they are requesting.
+
+## Group Membership
+
+The group membership tab gives an overview of all of the non-internal groups.
+
+![Group overview](/_static/images/features/core/groupmanagement/group-membership.png)
+
+### Group Member Management
+
+Clicking on the blue eye will take you to the group member management screen. Here you can see a list of people who are in the group, and remove members where necessary.
+
+![Group overview](/_static/images/features/core/groupmanagement/group-member-management.png)
+
+### Group Audit Log
+
+Whenever a user Joins, Leaves, or is Removed from a group, this is logged. To find the audit log for a given group, click the light-blue button to the right of the Group Member Management (blue eye) button.
+
+These logs contain the Date and Time the action was taken (in EVE/UTC), the user which submitted the request being acted upon (requestor), the user's main character, the type of request (join, leave or removed), the action taken (accept, reject or remove), and the user that took the action (actor).
+
+![Audit Log Example](/_static/images/features/core/groupmanagement/group_audit_log.png)
+
+```eval_rst
+.. note::
+    There is no tracking for "Open" groups as members are able to freely join/leave these groups.
+```
+
+## Group Leaders
+
+Group leaders have the same abilities as users with the `group_management` permission, _however_, they will only be able to:
+
+- Approve requests for groups they are a leader of.
+- View the Group Membership and Group Members of groups they are leaders of.
+
+This allows you to more finely control who has access to manage which groups. Currently it is not possible to add a Group as group leaders.

docs/features/core/groups.md

@@ -0,0 +1,50 @@
+# Groups
+
+Group Management is one of the core tasks of Alliance Auth. Many of Alliance Auth's services allow for synchronising of group membership, allowing you to grant permissions or roles in services to access certain aspects of them.
+
+## User Organized Groups
+
+Administrators can create custom groups for users to join. Examples might be groups like `Leadership`, `CEO` or `Scouts`.
+
+When you create a `Group` additional settings are available beyond the normal Django group model. The admin page looks like this:
+
+![AuthGroup Admin page](/_static/images/features/core/groupmanagement/group-admin.png)
+
+Here you have several options:
+
+### Internal
+
+Users cannot see, join or request to join this group. This is primarily used for Auth's internally managed groups, though can be useful if you want to prevent users from managing their membership of this group themselves. This option will override the Hidden, Open and Public options when enabled.
+
+By default, every new group created will be an internal group.
+
+### Hidden
+
+Group is hidden from the user interface, but users can still join if you give them the appropriate join link. The URL will be along the lines of `https://example.com/en/group/request_add/{group_id}`. You can get the Group ID from the admin page URL.
+
+This option still respects the Open option.
+
+### Open
+
+When a group is toggled open, users who request to join the group will be immediately added to the group. 
+
+If the group is not open, their request will have to be approved manually by someone with the group management role, or a group leader of that group.
+
+### Public
+
+Group is accessible to any registered user, even when they do not have permission to join regular groups.
+
+The key difference is that the group is completely unmanaged by Auth. **Once a member joins they will not be removed unless they leave manually, you remove them manually, or their account is deliberately set inactive or deleted.**
+
+Most people won't have a use for public groups, though it can be useful if you wish to allow public access to some services. You can grant service permissions on a public group to allow this behavior.
+
+## Permission
+
+In order to join a group other than a public group, the permission `groupmanagement.request_groups` (`Can request non-public groups` in the admin panel) must be active on their account, either via a group or directly applied to their User account.
+
+When a user loses this permission, they will be removed from all groups _except_ Public groups.
+
+```eval_rst
+.. note::
+    By default, the ``groupmanagement.request_groups`` permission is applied to the ``Member`` group. In most instances this, and perhaps adding it to the ``Blue`` group, should be all that is ever needed. It is unsupported and NOT advisable to apply this permission to a public group. See #697 for more information.
+```

docs/features/core/index.md

@@ -0,0 +1,13 @@
+# Core Features
+
+Managing access to applications and services is one of the core functions of **Alliance Auth**. The related key concepts and functionalities are describes in this section.
+
+```eval_rst
+.. toctree::
+    :maxdepth: 1
+
+    dashboard
+    states
+    groups
+    groupmanagement
+```

docs/features/core/states.md

@@ -0,0 +1,59 @@
+# States
+
+States define the basic role of a user based on his affiliation with your organization. A user that has a character in your organization (e.g. alliance) will usually have the `Member` state. And a user, that has no characters in your organization will usually have the `Guest` state.
+
+States are assigned and updated automatically. So a user which character just left your organization will automatically loose his `Member` state and get the `Guest` state instead.
+
+The main purpose of states like `Member` is to have one place where you can assign all permissions that should apply to all users with that particular state. For example if all your members should have access to the SRP app you would add the permission that gives access to the SRP app to the `Member` state.
+
+## Creating a State
+
+States are created through your installation's admin site. Upon install three states are created for you: `Member`, `Blue`, and `Guest`. New ones can be created like any other Django model by users with the appropriate permission (`authentication | state | Can add state`) or superusers.
+
+A number of fields are available and are described below.
+
+### Name
+
+This is the displayed name of a state. Should be self-explanatory.
+
+### Permissions
+
+This lets you select permissions to grant to the entire state, much like a group. Any user with this state will be granted these permissions.
+
+A common use case would be granting service access to a state.
+
+### Priority
+
+This value determines the order in which states are applied to users. Higher numbers come first. So if a random user `Bob` could member of both the `Member` and `Blue` states, because `Member` has a higher priority `Bob` will be assigned to it.
+
+### Public
+
+Checking this box means this state is available to all users. There isn't much use for this outside the `Guest` state.
+
+### Member Characters
+
+This lets you select which characters the state is available to. Characters can be added by selecting the green plus icon.
+
+### Member Corporations
+
+This lets you select which Corporations the state is available to. Corporations can be added by selecting the green plus icon.
+
+### Member Alliances
+
+This lets you select which Alliances the state is available to. Alliances can be added by selecting the green plus icon.
+
+## Determining a User's State
+
+States are mutually exclusive, meaning a user can only be in one at a time.
+
+Membership is determined based on a user's main character. States are tested in order of descending priority - the first one which allows membership to the main character is assigned to the user.
+
+States are automatically assigned when a user registers to the site, their main character changes, they are activated or deactivated, or states are edited. Note that editing states triggers lots of state checks so it can be a very slow process.
+
+Assigned states are visible in the `Users` section of the `Authentication` admin site.
+
+## The Guest State
+
+If no states are available to a user's main character, or their account has been deactivated, they are assigned to a catch-all `Guest` state. This state cannot be deleted nor can its name be changed.
+
+The `Guest` state allows permissions to be granted to users who would otherwise not get any. For example access to public services can be granted by giving the `Guest` state a service access permission.