Add some nice examples to the docs

knyghty · Mar 23, 2015 · 2f455dc · 2f455dc
1 parent 636723a
commit 2f455dc
Show file tree

Hide file tree

Showing 3 changed files with 61 additions and 3 deletions.
diff --git a/docs/examples.rst b/docs/examples.rst
@@ -0,0 +1,56 @@
+########
+Examples
+########
+
+
+**********************
+Adding Open Graph data
+**********************
+
+Adding arbitrary data is simple, just construct the model however you want:
+
+.. code-block:: python
+  from snakeoil.models import SeoModel
+
+  class MySeoModel(SeoModel):
+      og_title = models.CharField(max_length=255)
+      og_type = models.CharField(max_length=255, default='website')
+      ...
+
+      class Meta:
+          abstract = True
+
+You don't have to inherit from SeoModel if you don't want the default
+head_title and meta_description fields. Your new fields are accessible by their
+name, ie. ``{{ seo.og_title }}``.
+
+
+*****************************
+Making life easier for admins
+*****************************
+
+It's great that our admins can add SEO data for any object or URL, but we
+can make their life even easier by adding sensible defaults. If you're using
+class-based views, you can provide a default based on the
+ ``__str__()``/``__unicode__()`` methods of your models by constructing your
+base.html like so:
+
+.. code-block:: html
+  {% load snakeoil %}
+  {% get_seo_data %}
+  <head>
+      <title>
+          {% block title %}{% firstof seo.head_title object %}{% endblock %}
+          | My Website
+      </title>
+      ...
+  </head>
+
+Note that even if you override ``context_object_name`` in your view, you can
+still access it as ``object`` in the template.
+
+Now we have default values for our objects, but what about our
+non-``DetailView`` pages? No problem, just override the block with whatever you want:
+
+.. code-block:: html
+  {% block title %}{% firstof seo.head_title 'Home' %}{% endblock %}
diff --git a/docs/index.rst b/docs/index.rst
@@ -9,6 +9,7 @@ Contents:
 
    quickstart
    reference
+   examples
 
 
 django-snakeoil provides SEO data (meta description, etc.) to your templates.

diff --git a/docs/reference.rst b/docs/reference.rst
@@ -12,8 +12,9 @@ Installation
   .. code-block:: python
 
     from django.conf.global_settings import TEMPLATE_CONTEXT_PROCESSORS as TCP
-    TEMPLATE_CONTEXT_PROCESSORS = TCP +
-    ('django.core.context_processors.request',)
+    TEMPLATE_CONTEXT_PROCESSORS = TCP + (
+        'django.core.context_processors.request',
+    )
 3. Add ``'snakeoil'`` to your INSTALLED_APPS
 
 
@@ -87,7 +88,7 @@ It might be useful to provide sensible defaults, such as:
 
 .. code-block:: html
 
-  <title>{% firstof seo.head_title object.title %} - My Site</title>
+  <title>{% firstof seo.head_title object %} - My Site</title>
 
 If you want to name your variable something else, maybe because you're already
 using seo for something else, or are using snakeoil for non-SEO data, the