more docs moved over to gitbook

docs/Auth.md

@@ -0,0 +1,40 @@
+User Authentication
+===================
+
+Misago adds additional layer of security around admin areas in your site. This means that unless you've signed to admin area directly, you have to authenticate yourself one more time to upgrade your session from "casual" one to "administrator".
+
+This mechanism was put in place because it's common for forum administrators to browse and use forums while signed on their administrator account. By default, Django requires user to be signed in and have special `is_staff` set on his or her account and know the path to administration backend to administrate site, which is good approach for situations when staff accounts are used exclusively for administration and not day to day usage.
+
+In addition for re-authentication requirement, Misago also monitors inactivity periods between requests to admin interfaces, and if one exceeds length specified in `MISAGO_ADMIN_SESSION_EXPIRATION` setting, it will assume that administrator has been inactive and request another reauthentication upon next request to admin backend.
+
+Implementation in this mechanism is placed within `misago.admin.auth` module and `misago.admin.middleware.AdminAuthMiddleware` middleware. Middleware uses methods from `auth` to detect if request is pointed at protected namespace, and if it is, it uses facilities to handle and control state of administrators session.
+
+
+### `misago.admin.auth.is_admin_session(request)`
+
+Returns true if current request has valid administrator session. Otherwhise returns false.
+
+
+### `misago.admin.auth.start_admin_session(request, user)`
+
+Promotes current session to state of administrator session.
+
+
+### `misago.admin.auth.update_admin_session(request)`
+
+Updates last activity timestamp on admin session.
+
+
+### `misago.admin.auth.close_admin_session(request)`
+
+Closes current admin session, degrading it to "casual" session and keeps user signed in.
+
+
+## Testing Admin views using test client
+
+To test protected admin views from within your test cases, you have to open valid admin session for test client. Misago provides `misago.admin.testutils.admin_login` function for this purpose.
+
+
+### `misago.admin.testutils.admin_login(client, username, password)`
+
+This function will make provided test client instance use valid admin session during test requests. Note that internally this function makes POST request to `misago:admin:index` link that should result with admin login form for unauthenticated users.

docs/Cache.md

@@ -0,0 +1,107 @@
+Cache
+=====
+
+Misago uses caching aggressivelly to save costful operations results like users ACLs resolution. Setting up cache, perfectly memory based one like Memcached is great way to speed up your forum and cut down database traffic.
+
+
+## Setting up Misago-only cache
+
+You can make Misago use its own cache instead of sharing cache with rest of your Django site. To do so, add new cache named `misago` to your `CACHES` setting:
+
+``python
+CACHES = {
+    'default': {
+        'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
+        'LOCATION': '127.0.0.1:11211',
+    },
+    'misago': {
+        'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
+        'LOCATION': '127.0.0.1:11212',
+    }
+}
+``
+
+## Cache buster
+
+Cache buster is small feature that allows certain cache-based systems find out when data they were dependant on has been changed, making their cache no longer valid.
+
+Cache buster lives in `misago.core.cachebuster` and provides following API:
+
+
+#### `is_valid(cache_name, version)`
+
+Checks if specific cache version is valid or raises ValueError if cache key is invalid.
+
+
+#### `get_version(cache_name)`
+
+Returns current valid cache version as an integer number or raises ValueError if cache key is invalid.
+
+
+#### `invalidate(cache_name)`
+
+Makes specified cache invalid.
+
+
+#### `invalidate_all()`
+
+Makes all versioned caches invalid.
+
+
+### Example usage
+
+Below snippet of code tests if cache version stored on `ban['version']` is current for bans cache:
+
+```python
+bans_cache_version = get_version('bans')
+if not cachebuster.is_valid('bans', ban['version']):
+    raise RuntimeError("ban was set before cache got invalidated and needs to be re-checked!")
+```
+
+
+### Adding Custom Cache Buster
+
+You may add and remove your own cache names to cache buster by using following commands:
+
+##### Note
+
+Don't forget to call `invalidate_all` function after adding or removing cache name from buster to force it to rebuild its own cache.
+
+
+#### `register(cache)`
+
+Registers new cache in cache buster for tracking.
+
+
+#### `unregister(cache)`
+
+Removes cache from cache buster and disables its tracking. This function will raise `ValueError` if cache you are trying to unregister is not registered.
+
+
+#### Registering cachebusters in migrations
+
+Misago provides the `misago.core.migrationutils.cachebuster_unregister_cache(apps, cache)` utility command for setting cachebusters in migrations, like such:
+
+```python
+# -*- coding: utf-8 -*-
+from __future__ import unicode_literals
+
+from django.db import migrations, models
+
+from misago.core.migrationutils import cachebuster_register_cache
+
+
+def register_bans_version_tracker(apps, schema_editor):
+    cachebuster_register_cache(apps, 'misago_bans')
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ('misago_core', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.RunPython(register_bans_version_tracker),
+    ]
+
+```

docs/SUMMARY.md

@@ -1,10 +1,13 @@
 # Table of contents
 
 * [Introduction](./README.md)
-* [Setup and Maintenance](./SetupMaintenance.md)
+* [Setup and maintenance](./SetupMaintenance.md)
 * [Upgrading from Misago 0.5](./UpgradingFrom05.md)
 * [Coding style](./CodingStyle.md)
+* [User authentication](./Auth.md)
+* [Writing new admin actions](./WritingNewAdminActions.md)
 * [Permissions framework](./PermissionsFramework.md)
+* [Cache](./Cache.md)
 * [Settings](./settings/README.md)
   * [Core settings](./settings/Core.md)
   * [Database settings](./settings/Database.md)

docs/SetupMaintenance.md

@@ -1,4 +1,4 @@
-Setup and Maintenance
+Setup and maintenance
 =====================
 
 Misago is Python and Django application which means system requirements as well as setup process and way maintenace taks are performed may appear confusing and suprising to administrators that have no experience outside of running PHP solutions.
@@ -87,6 +87,6 @@ Misago is de facto Django with extra features added. This means deployment of Mi
 If you need example, UWSGI project's documentation has tutorial on configuring NGINX with UWSGI to run [django applications](http://uwsgi-docs.readthedocs.io/en/latest/WSGIquickstart.html).
 
 
-### Securing MEDIA_ROOT
+### Securing `MEDIA_ROOT`
 
 By default Misago uses the `FileSystemStorage` strategy that stores user-uploaded files in your site's `media` directory. You need to make sure that you have disabled indexing/listing of this directory contents in your HTTP server's settings, or your user-uploaded files will be easily discoverable from internet. This is especially important because Misago has no special protection system in place for uploaded files.