Drafted docs for TimeGateView

docs/genericviews.rst

@@ -26,7 +26,7 @@ MementoDetailView
 
     .. py:attribute:: datetime_field
 
-        A string attribute that is the name of the database field that contains the timestamp when the resource was archived. Required.
+        A string attribute that is the name of the database field that contains the timestamp when the resource was archived. Default ``'datetime'``.
 
     .. py:attribute:: timemap_pattern_name
 
@@ -42,6 +42,7 @@ MementoDetailView
 
         from memento.timegate import MementoDetailView
 
+
         class ExampleMementoDetailView(MementoDetailView):
             """
             A Memento-enabled detail page for a screenshot in my example
@@ -82,10 +83,71 @@ TimemapLinkList
 
     Returns a queryset list in Memento's Timemap format.
 
+
 TimeGateView
 ------------
 
 .. py:class:: TimeGateView(RedirectView)
 
-    A Memento TimeGate that parses a request from the headers and redirects to the corresponding Memento detail page.
+    Creates a TimeGate that handles a request with a 'Accept-Datetime' headers and returns a response that redirects to the corresponding Memento.
+
+    .. attribute:: model
+
+        A Django database model where the object will be drawn with a ``Model.objects.filter()`` query. Optional. If you want to provide a more specific list, define the ``queryset`` attribute instead.
+
+    .. attribute:: queryset
+
+        The list of objects that will be provided to the template. Can be any iterable of items, not just a Django queryset. Optional, but if this attribute is not defined the ``model`` attribute must be defined.
+
+    .. py:attribute:: datetime_field
+
+        A string attribute that is the name of the database field that contains the timestamp when the resource was archived. Default ``'datetime'``.
+
+    .. py:attribute:: url_kwarg
+
+        The name for the keyword argument in the URL pattern that will be used to filter the queryset down to objects archived for the resource. Default ``'url'``.
+
+    .. py:attribute:: url_field
+
+        A string attribute that is the name of the database field that contains
+        the original URL archived. Defailt ``'url'``.
+
+    .. py:attribute:: timemap_pattern_name
+
+        The name of the URL pattern for this site's TimeMap that, given the original url, is able to reverse to return the location of the map that serves as the directory of all versions of this resource archived by your site. Optional.
+
+    **Example myapp/views.py**
+
+    .. code-block:: python
+
+        from memento.timegate import TimeGateView
+
+
+        class ExampleTimeGateView(TimeGateView):
+            """
+            A Memento TimeGate that, given a timestamp, will redirect to the detail page for a screenshot in my example archive
+
+            It is linked to a url that looks like something like:
+
+                url(
+                    r'^timegate/(?P<url>.*)$',
+                    views.ExampleTimeGateView.as_view(),
+                    name="timegate"
+                ),
+
+            """
+            model = Screenshot
+            url_field = 'site__url' # You can walk across ForeignKeys like normal
+            datetime_field = 'timestamp'
+            timemap_pattern_name = "timemap-screenshot"
+
+    **Example response**
+
+    .. code-block:: bash
 
+        $ curl -X HEAD -i http://www.example.com/timegate/http://archivedsite.com/ --header "Accept-Datetime: Fri, 1 May 2015 00:01:00 GMT"
+        HTTP/1.1 302 Moved Temporarily
+        Server: Apache/2.2.22 (Ubuntu)
+        Link: <http://archivedsite.com/>; rel="original", <http://www.example.com/timemap/link/http://archivedsite.com/>; rel="timemap"; type="application/link-format"
+        Location: http://www.example.com/screenshot/100/
+        Vary: accept-datetime

memento/timegate/views.py

@@ -44,6 +44,10 @@ class MementoDetailView(DetailView):
     timemap_pattern_name = None
 
     def get_timemap_url(self, request, url):
+        """
+        Returns the location of the TimeMap that lists resources archived
+        for the provided URL.
+        """
         path = reverse(self.timemap_pattern_name, kwargs={'url': url})
         current_site = get_current_site(request)
         return add_domain(
@@ -77,8 +81,9 @@ def get(self, request, *args, **kwargs):
 
 class TimeGateView(RedirectView):
     """
-    A Memento TimeGate that parses a request from the headers
-    and redirects to the corresponding Memento detail page.
+    Creates a TimeGate that handles a request with Memento headers
+    and returns a response that redirects to the corresponding
+    Memento.
     """
     model = None
     queryset = None
@@ -88,6 +93,10 @@ class TimeGateView(RedirectView):
     datetime_field = 'datetime'
 
     def parse_datetime(self, request):
+        """
+        Parses the requested datetime from the request headers
+        and returns it if it exists. Otherwise returns None.
+        """
         # Verify that the Accept-Datetime header is provided
         if not request.META.get("HTTP_ACCEPT_DATETIME"):
             return None
@@ -102,6 +111,10 @@ def parse_datetime(self, request):
         return dt
 
     def get_object(self, url, dt):
+        """
+        Accepts the requested URL and datetime and returns the object
+        with the smallest date difference.
+        """
         queryset = self.get_queryset()
         queryset = queryset.filter(**{self.url_field: url})
 
@@ -131,6 +144,9 @@ def get_object(self, url, dt):
                 return next_obj
 
     def get_most_recent_object(self, url):
+        """
+        Returns the most recently archive object of the submitted URL
+        """
         queryset = self.get_queryset()
         try:
             return queryset.filter(**{
@@ -160,6 +176,9 @@ def get_queryset(self):
         return self.queryset.all()
 
     def get_redirect_url(self, request, obj):
+        """
+        Returns the URL that will redirect to the Memento resource.
+        """
         current_site = get_current_site(request)
         return add_domain(
             current_site.domain,
@@ -168,6 +187,10 @@ def get_redirect_url(self, request, obj):
         )
 
     def get_timemap_url(self, request, url):
+        """
+        Returns the location of the TimeMap that lists resources archived
+        for the provided URL.
+        """
         path = reverse(self.timemap_pattern_name, kwargs={'url': url})
         current_site = get_current_site(request)
         return add_domain(