From 5f83b4a423c8fa8adac24dc9c8d7b75741f80c07 Mon Sep 17 00:00:00 2001
From: Karl Hobley <karl@torchbox.com>
Date: Fri, 11 Jul 2014 14:25:14 +0100
Subject: [PATCH] Improvements to PageQuerySet docs

---
 docs/building_your_site/djangodevelopers.rst | 118 ++++++++++++++++---
 wagtail/wagtailcore/query.py                 |   9 ++
 2 files changed, 109 insertions(+), 18 deletions(-)

diff --git a/docs/building_your_site/djangodevelopers.rst b/docs/building_your_site/djangodevelopers.rst
index 719d92af24..a2d1963795 100644
--- a/docs/building_your_site/djangodevelopers.rst
+++ b/docs/building_your_site/djangodevelopers.rst
@@ -230,8 +230,8 @@ In addition to the model fields provided, ``Page`` has many properties and metho
     .. automethod:: search
 
 
-Page Queryset
-~~~~~~~~~~~~~
+Page Queryset Reference
+~~~~~~~~~~~~~~~~~~~~~~~
 
 All models that inherit from ``Page`` are given some extra Queryset methods accessible from their ``.objects`` attribute.
 
@@ -262,10 +262,30 @@ Examples:
 
     .. automethod:: live
 
+        Example:
+
+        .. code-block:: python
+
+            published_pages = Page.objects.live()
+
     .. automethod:: not_live
 
+        Example:
+
+        .. code-block:: python
+
+            unpublished_pages = Page.objects.not_live()
+
     .. automethod:: in_menu
 
+        Example:
+
+        .. code-block:: python
+
+            # Build a menu from live pages that are children of the homepage
+            menu_items = homepage.get_children().live().in_menu()
+
+
         .. note::
 
             To put your page in menus, set the show_in_menus flag to true:
@@ -275,50 +295,112 @@ Examples:
                 # Add 'my_page' to the menu
                 my_page.show_in_menus = True
 
-    .. automethod:: not_in_menu
-
     .. automethod:: page
 
-        .. note::
+        Example:
 
-            This will not add the page to the queryset if it doesn't already contain it.
+        .. code-block:: python
 
-            If you would like to add a page to a queryset, create another queryset with just
-            that page and combine them with the ``|`` operator:
-
-            .. code-block:: python
-
-                # Force `my_page` into `queryset`
-                queryset = queryset | Page.objects.page(my_page)
+            # Append an extra page to a queryset
+            new_queryset = old_queryset | Page.objects.page(page_to_add)
 
     .. automethod:: not_page
 
+        Example:
+
+        .. code-block:: python
+
+            # Remove a page from a queryset
+            new_queryset = old_queryset & Page.objects.not_page(page_to_remove)
+
     .. automethod:: descendant_of
 
+        Example:
+
+        .. code-block:: python
+
+            # Get EventPages that are under the special_events Page
+            special_events = EventPage.objects.descendant_of(special_events_index)
+
+            # Alternative way
+            special_events = special_events_index.get_descendants()
+
     .. automethod:: not_descendant_of
 
+        Example:
+
+        .. code-block:: python
+
+            # Get EventPages that are not under the archived_events Page
+            non_archived_events = EventPage.objects.not_descendant_of(archived_events_index)
+
     .. automethod:: child_of
 
-    .. automethod:: not_child_of
+        Example:
+
+        .. code-block:: python
+
+            # Get a list of sections
+            sections = Page.objects.child_of(homepage)
+
+            # Alternative way
+            sections = homepage.get_children()
 
     .. automethod:: ancestor_of
 
+        Example:
+
+        .. code-block:: python
+
+            # Get the current section
+            current_section = Page.objects.ancestor_of(current_page).child_of(homepage).first()
+
+            # Alternative way
+            current_section = current_page.get_ancestors().child_of(homepage).first()
+
     .. automethod:: not_ancestor_of
 
+        Example:
+
+        .. code-block:: python
+
+            # Get the other sections
+            other_sections = Page.objects.not_ancestor_of(current_page).child_of(homepage)
+
     .. automethod:: sibling_of
 
-    .. automethod:: not_sibling_of
+        Example:
 
-    .. automethod:: type
+        .. code-block:: python
 
-    .. automethod:: not_type
+            # Get list of siblings
+            siblings = Page.objects.sibling_of(current_page)
+
+            # Alternative way
+            siblings = current_page.get_siblings()
 
     .. automethod:: public
 
-    .. automethod:: not_public
+        .. note::
+
+            This doesn't filter out unpublished pages. If you want to only have published public pages, use ``.live().public()``
+
+        Example:
+
+        .. code-block:: python
+
+            # Find all the pages that are viewable by the public
+            all_pages = Page.objects.live().public()
 
     .. automethod:: search
 
+        Example:
+
+        .. code-block:: python
+
+            # Search future events
+            results = EventPage.objects.live().filter(date__gt=timezone.now()).search("Hello")
+
 
 .. _wagtail_site_admin:
 
diff --git a/wagtail/wagtailcore/query.py b/wagtail/wagtailcore/query.py
index b6bf9c9113..81d78dc379 100644
--- a/wagtail/wagtailcore/query.py
+++ b/wagtail/wagtailcore/query.py
@@ -177,11 +177,20 @@ class PageQuerySet(MP_NodeQuerySet):
         return q
 
     def public(self):
+        """
+        This filters the queryset to only contain pages that are not in a private section
+        """
         return self.filter(self.public_q())
 
     def not_public(self):
+        """
+        This filters the queryset to only contain pages that are in a private section
+        """
         return self.exclude(self.public_q())
 
     def search(self, query_string, fields=None, backend='default'):
+        """
+        This runs a search query on all the pages in the queryset
+        """
         search_backend = get_search_backend(backend)
         return search_backend.search(query_string, self, fields=None)