Update Documentation (#23)

Author: adinhodovic

docs/conf.py

@@ -0,0 +1,48 @@
+# Configuration
+
+The configuration is a list of dicts and each dict consists of three fields, one being mandatory and the other two being optional:
+
+- id(string, required): Experiment id required to identify each experiment in the cookie set by Google.
+- alias(string, optional): Alias for the experiment id, useful for clarity when accessing experiment variants by key.
+- variant_aliases(dict, optional): Aliases for each variant, consist of key-value variables. The key represents the index for each experiment variant. The value is the alias for the variant. Check your Google Optimize experiment to see which index represents what experiment variant.
+
+## Single experiment
+
+For a single experiment the settings could be the following:
+
+```py
+# django-google-optimize
+GOOGLE_OPTIMIZE_EXPERIMENTS = [
+    {
+        "id": "utSuKi3PRbmxeG08en8VNw",
+        "alias": "redesign",
+        "variant_aliases": {0: "old_design", 1: "new_design"},
+    }
+]
+```
+
+## Multiple experiments
+
+For multiple experiments the settings could be the following:
+
+```py
+# django-google-optimize
+GOOGLE_OPTIMIZE_EXPERIMENTS = [
+    {
+        "id": "3x8_BbSCREyqtWm1H1OUrQ",
+        "alias": "redesign_page",
+        "variant_aliases": {0: "old_design", 1: "new_design"},
+    },
+    {
+        "id": "7IXTpXmLRzKwfU-Eilh_0Q",
+        "alias": "redesign_header",
+        "variant_aliases": {0: "old_header", 1: "new_header"},
+    },
+]
+```
+
+## Notes
+
+If you do not set the alias you'll have to access the experiment variant by the Google Optimize id for the experiment.
+
+If you do not set the variant alias for a variant the index will be the variant returned.

docs/configuration.md

@@ -0,0 +1,9 @@
+# Welcome to django-google-optimize's documentation!
+
+django-google-optimize is a reusable Django application designed to make running server side Google Optimize A/B test easy.
+
+## Contents
+
+* [Installation](./installation.md)
+* [Configuration](./configuration.md)
+* [Usage](./usage.md)

docs/getting_started.rst

@@ -0,0 +1,40 @@
+# Installing django-google-optimize
+
+Install django-google-optimize with pip:
+
+`pip install django-google-optimize`
+
+Add the application to installed django applications:
+
+```py
+DJANGO_APPS = [
+    ...
+    "django_google_optimize",
+    ...
+]
+```
+
+Add the middleware:
+
+```py
+MIDDLEWARE = [
+    ...
+    "django_google_optimize.middleware.google_optimize",
+    ...
+]
+```
+
+If you want to access the request in your templates remember to add the request context processor:
+
+```python
+TEMPLATES = [
+    {
+        "BACKEND": "django.template.backends.django.DjangoTemplates",
+        "APP_DIRS": True,
+        "DIRS": [path.join(path.dirname(__file__), "templates"),],
+        "OPTIONS": {
+            "context_processors": ["django.template.context_processors.request",]
+        },
+    }
+]
+```

docs/index.md

@@ -0,0 +1,45 @@
+# Usage
+
+## Usage in templates
+
+If you are redesigning major changes then you maybe would like to have two different templates. You can create a file that is called `jobs/xyz.html` that target two different files based on the experiment variant.
+
+`jobs/xyz.html`
+
+```django
+{% if request.google_optimize.redesign == "new_design" %}
+{% include "jobs/xyz_new.html" %}
+{% else %}
+{% include "jobs/xyz_old.html" %}
+{% endif %}
+```
+
+Or you can use `django-google-optimize` inline within a single template:
+
+```django
+<nav class="navbar navbar-expand-lg navbar-dark
+{% if request.google_optimize.redesign == "new_design" %} navbar-redesign{% endif %}
+">
+```
+
+## Usage in views
+
+To display two different templates based on the experiment variant:
+
+```python
+def get_template_names(self):
+    variant = request.google_optimize.get("redesign", None)
+    if variant == "new":
+        return ["jobs/xyz_new.html"]
+    return ["jobs/xyz_old.html"]
+```
+
+Adjust the queryset based of the experiment variant:
+
+```python
+def get_queryset(self):
+    variant = self.request.google_optimize.get("redesign", None)
+
+    if variant == "new":
+        qs = qs.exclude(design__contains="old")
+```

docs/index.rst

@@ -0,0 +1,16 @@
+---
+site_name: django-google-optimize
+nav:
+    - Home: index.md
+    - Installation: installation.md
+    - Configuration: configuration.md
+    - Usage: usage.md
+theme: readthedocs
+repo_url: https://github.com/adinhodovic/django-google-optimize/
+site_url: https://github.com/adinhodovic/django-google-optimize/
+copyright: Adin Hodovic and individual contributors
+site_author: Adin Hodovic
+
+extra:
+    version: 0.1
+    release: 0.1.7

docs/installation.md

@@ -47,8 +47,8 @@ deps =
 commands = pylint django_google_optimize tests
 
 [testenv:docs]
-deps = sphinx
-commands = sphinx-build -n -W docs docs/_build
+deps = mkdocs
+commands = mkdocs build
 
 [testenv:release]
 deps =