From 9dd4b0391a2ea4c172e953dde28dd7c4acc1a55f Mon Sep 17 00:00:00 2001
From: Karl Hobley <karlhobley10@gmail.com>
Date: Mon, 18 May 2015 11:36:40 +0100
Subject: [PATCH] Improvements to Page model reference docs

- Rename to "Page model reference"
- Add docs for fields
- Add docs for other models such as revisions, group page permissions, etc
---
 docs/reference/pages/index.rst                |  2 +-
 ...erties_methods.rst => model_reference.rst} | 96 ++++++++++++++++++-
 wagtail/wagtailcore/models.py                 | 12 ++-
 3 files changed, 101 insertions(+), 9 deletions(-)
 rename docs/reference/pages/{attributes_properties_methods.rst => model_reference.rst} (58%)

diff --git a/docs/reference/pages/index.rst b/docs/reference/pages/index.rst
index dba9e6590f..a0c8a7cc0c 100644
--- a/docs/reference/pages/index.rst
+++ b/docs/reference/pages/index.rst
@@ -20,4 +20,4 @@ The presentation of your content, the actual webpages, includes the normal use o
     sites
     advanced_topics/queryset_methods
     advanced_topics/private_pages
-    attributes_properties_methods
+    model_reference
diff --git a/docs/reference/pages/attributes_properties_methods.rst b/docs/reference/pages/model_reference.rst
similarity index 58%
rename from docs/reference/pages/attributes_properties_methods.rst
rename to docs/reference/pages/model_reference.rst
index 04f2d6b1dc..a0956221ff 100644
--- a/docs/reference/pages/attributes_properties_methods.rst
+++ b/docs/reference/pages/model_reference.rst
@@ -1,9 +1,54 @@
-Page Attributes, Properties and Methods Reference
--------------------------------------------------
+Page model Reference
+====================
+
+.. automodule:: wagtail.wagtailcore.models
+
+
+Fields
+------
+
+.. glossary::
+
+    ``title`` (text)
+
+        The title of the page (set in the admin).
+
+    ``slug`` (text)
+
+        The slug of the page (set in the admin). This is used for constructing the page's URL.
+
+    ``content_type`` (foreign key)
+
+        A foreign key to the :class:`~django.contrib.contenttypes.models.ContentType` object that represents the specific model of this page.
+
+    ``live`` (boolean)
+
+        A boolean that is set to ``True`` if the page is published.
+
+        Note: this field defaults to ``True`` meaning that any pages that are created programmatically will be published by default.
+
+    ``has_unpublished_changes`` (boolean)
+
+        A boolean that is set to ``True`` when the page is either in draft or published with draft changes.
+
+    ``owner`` (foreign key)
+
+        A foreign key to the user that created the page.
+
+    ``first_published_at`` (date/time)
+
+        The date/time when the page was first published.
+
+..    ``seo_title`` (text)
+..    ``show_in_menus`` (boolean)
+..    ``search_description`` (text)
+
+
+Other methods, attributes and properties
+----------------------------------------
 
 In addition to the model fields provided, ``Page`` has many properties and methods that you may wish to reference, use, or override in creating your own models. Those listed here are relatively straightforward to use, but consult the Wagtail source code for a full view of what's possible.
 
-.. automodule:: wagtail.wagtailcore.models
 .. autoclass:: Page
 
     .. autoattribute:: specific
@@ -79,3 +124,48 @@ In addition to the model fields provided, ``Page`` has many properties and metho
     .. attribute:: password_required_template
 
         Defines which template file should be used to render the login form for Protected pages using this model. This overrides the default, defined using ``PASSWORD_REQUIRED_TEMPLATE`` in your settings. See :ref:`private_pages`
+
+
+Other models
+------------
+
+``Site``
+~~~~~~~~
+
+.. autoclass:: Site
+
+    .. automethod:: find_for_request
+
+    .. autoattribute:: root_url
+
+    .. automethod:: get_site_root_paths
+
+``PageRevision``
+~~~~~~~~~~~~~~~~
+
+.. autoclass:: PageRevision
+
+    .. automethod:: as_page_object
+
+    .. automethod:: approve_moderation
+
+    .. automethod:: reject_moderation
+
+    .. automethod:: is_latest_revision
+
+    .. automethod:: publish
+
+``GroupPagePermission``
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: GroupPagePermission
+
+``PageViewRestriction``
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: PageViewRestriction
+
+``Orderable`` (abstract)
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: Orderable
diff --git a/wagtail/wagtailcore/models.py b/wagtail/wagtailcore/models.py
index c6b0ff9c78..25d184d537 100644
--- a/wagtail/wagtailcore/models.py
+++ b/wagtail/wagtailcore/models.py
@@ -70,11 +70,13 @@ class Site(models.Model):
         """
         Find the site object responsible for responding to this HTTP
         request object. Try:
-         - unique hostname first
-         - then hostname and port
-         - if there is no matching hostname at all, or no matching
-           hostname:port combination, fall back to the unique default site,
-           or raise an exception
+
+        * unique hostname first
+        * then hostname and port
+        * if there is no matching hostname at all, or no matching
+          hostname:port combination, fall back to the unique default site,
+          or raise an exception
+
         NB this means that high-numbered ports on an extant hostname may
         still be routed to a different hostname which is set as the default
         """