From fe1110018ae98dec8d62d83f4672313e246f4170 Mon Sep 17 00:00:00 2001 From: Gabriel Hurley Date: Fri, 18 Feb 2011 00:58:34 +0000 Subject: [PATCH] Fixed #15335 -- Improved Sphinx crossref targets and metadata for the sites and flatpages reference docs. git-svn-id: http://code.djangoproject.com/svn/django/trunk@15562 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/contrib/flatpages.txt | 46 ++++++++++++--------- docs/ref/contrib/sites.txt | 74 +++++++++++++++++++++++++--------- 2 files changed, 83 insertions(+), 37 deletions(-) diff --git a/docs/ref/contrib/flatpages.txt b/docs/ref/contrib/flatpages.txt index 9bdd4ba006..0411e8f93f 100644 --- a/docs/ref/contrib/flatpages.txt +++ b/docs/ref/contrib/flatpages.txt @@ -47,6 +47,8 @@ To install the flatpages app, follow these steps: 4. Run the command :djadmin:`manage.py syncdb `. +.. currentmodule:: django.contrib.flatpages.middleware + How it works ============ @@ -56,25 +58,29 @@ that simply maps a URL to a title and bunch of text content. ``django_flatpage_sites`` associates a flatpage with a site. The :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` -does all of the work. Each time any Django application raises a 404 error, this -middleware checks the flatpages database for the requested URL as a last resort. -Specifically, it checks for a flatpage with the given URL with a site ID that -corresponds to the :setting:`SITE_ID` setting. +does all of the work. -If it finds a match, it follows this algorithm: +.. class:: FlatpageFallbackMiddleware - * If the flatpage has a custom template, it loads that template. Otherwise, - it loads the template :file:`flatpages/default.html`. + Each time any Django application raises a 404 error, this middleware + checks the flatpages database for the requested URL as a last resort. + Specifically, it checks for a flatpage with the given URL with a site ID + that corresponds to the :setting:`SITE_ID` setting. - * It passes that template a single context variable, :data:`flatpage`, which - is the flatpage object. It uses - :class:`~django.template.context.RequestContext` in rendering the - template. + If it finds a match, it follows this algorithm: -If it doesn't find a match, the request continues to be processed as usual. + * If the flatpage has a custom template, it loads that template. + Otherwise, it loads the template :file:`flatpages/default.html`. -The middleware only gets activated for 404s -- not for 500s or responses of any -other status code. + * It passes that template a single context variable, ``flatpage``, + which is the flatpage object. It uses + :class:`~django.template.RequestContext` in rendering the + template. + + If it doesn't find a match, the request continues to be processed as usual. + + The middleware only gets activated for 404s -- not for 500s or responses + of any other status code. .. admonition:: Flatpages will not apply view middleware @@ -104,6 +110,8 @@ For more on middleware, read the :doc:`middleware docs :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` will not attempt to serve a flat page. +.. currentmodule:: django.contrib.flatpages.models + How to add, change and delete flatpages ======================================= @@ -117,7 +125,7 @@ other object in the system. Via the Python API ------------------ -.. class:: models.FlatPage +.. class:: FlatPage Flatpages are represented by a standard :doc:`Django model `, @@ -126,6 +134,8 @@ Via the Python API .. _django/contrib/flatpages/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/flatpages/models.py +.. currentmodule:: django.contrib.flatpages + Flatpage templates ================== @@ -141,7 +151,7 @@ Creating the :file:`flatpages/default.html` template is your responsibility; in your template directory, just create a :file:`flatpages` directory containing a file :file:`default.html`. -Flatpage templates are passed a single context variable, :data:`flatpage`, +Flatpage templates are passed a single context variable, ``flatpage``, which is the flatpage object. Here's a sample :file:`flatpages/default.html` template: @@ -164,7 +174,7 @@ both ``flatpage.title`` and ``flatpage.content`` are marked as **not** requiring :ref:`automatic HTML escaping ` in the template. -Getting a list of :class:`~django.contrib.flatpages.models.Flatpage` objects in your templates +Getting a list of :class:`~django.contrib.flatpages.models.FlatPage` objects in your templates ============================================================================================== .. versionadded:: 1.3 @@ -194,7 +204,7 @@ Displaying ``registration_required`` flatpages ---------------------------------------------- By default, the :ttag:`get_flatpages` templatetag will only show -flatpages that are marked :attr:`registration_required`\=False. If you +flatpages that are marked ``registration_required = False``. If you want to display registration-protected flatpages, you need to specify an authenticated user using a``for`` clause. diff --git a/docs/ref/contrib/sites.txt b/docs/ref/contrib/sites.txt index b5039938c9..4730cb2e63 100644 --- a/docs/ref/contrib/sites.txt +++ b/docs/ref/contrib/sites.txt @@ -6,6 +6,8 @@ The "sites" framework :synopsis: Lets you operate multiple Web sites from the same database and Django project +.. currentmodule:: django.contrib.sites.models + Django comes with an optional "sites" framework. It's a hook for associating objects and functionality to particular Web sites, and it's a holding place for the domain names and "verbose" names of your Django-powered sites. @@ -15,13 +17,21 @@ need to differentiate between those sites in some way. The whole sites framework is based on a simple model: -.. class:: django.contrib.sites.models.Site +.. class:: Site + + A model for storing the ``domain`` and ``name`` attributes of a Web site. + The :setting:`SITE_ID` setting specifies the database ID of the + :class:`~django.contrib.sites.models.Site` object associated with that + particular settings file. + + .. attribute:: domain + + The domain name associated with the Web site. + + .. attribute:: name + + A human-readable "verbose" name for the Web site. -This model has :attr:`~django.contrib.sites.models.Site.domain` and -:attr:`~django.contrib.sites.models.Site.name` fields. The :setting:`SITE_ID` -setting specifies the database ID of the -:class:`~django.contrib.sites.models.Site` object associated with that -particular settings file. How you use this is up to you, but Django uses it in a couple of ways automatically via simple conventions. @@ -85,9 +95,10 @@ This accomplishes several things quite nicely: Associating content with a single site -------------------------------------- -Similarly, you can associate a model to the :class:`~django.contrib.sites.models.Site` +Similarly, you can associate a model to the +:class:`~django.contrib.sites.models.Site` model in a many-to-one relationship, using -:class:`~django.db.models.fields.related.ForeignKey`. +:class:`~django.db.models.ForeignKey`. For example, if an article is only allowed on a single site, you'd use a model like this:: @@ -158,6 +169,15 @@ the sites framework is installed) or a RequestSite instance (if it is not). This allows loose coupling with the sites framework and provides a usable fallback for cases where it is not installed. +.. versionadded:: 1.3 + +.. function:: get_current_site(request) + + Checks if contrib.sites is installed and returns either the current + :class:`~django.contrib.sites.models.Site` object or a + :class:`~django.contrib.sites.models.RequestSite` object based on + the request. + Getting the current domain for display -------------------------------------- @@ -260,10 +280,12 @@ clear the cache using ``Site.objects.clear_cache()``:: Site.objects.clear_cache() current_site = Site.objects.get_current() +.. currentmodule:: django.contrib.sites.managers + The ``CurrentSiteManager`` ========================== -.. class:: django.contrib.sites.managers.CurrentSiteManager +.. class:: CurrentSiteManager If :class:`~django.contrib.sites.models.Site` plays a key role in your application, consider using the helpful @@ -300,9 +322,9 @@ How did :class:`~django.contrib.sites.managers.CurrentSiteManager` know which field of ``Photo`` was the :class:`~django.contrib.sites.models.Site`? By default, :class:`~django.contrib.sites.managers.CurrentSiteManager` looks for a -either a :class:`~django.db.models.fields.related.ForeignKey` called +either a :class:`~django.db.models.ForeignKey` called ``site`` or a -:class:`~django.db.models.fields.related.ManyToManyField` called +:class:`~django.db.models.ManyToManyField` called ``sites`` to filter on. If you use a field named something other than ``site`` or ``sites`` to identify which :class:`~django.contrib.sites.models.Site` objects your object is @@ -325,7 +347,7 @@ demonstrates this:: on_site = CurrentSiteManager('publish_on') If you attempt to use :class:`~django.contrib.sites.managers.CurrentSiteManager` -and pass a field name that doesn't exist, Django will raise a :exc:`ValueError`. +and pass a field name that doesn't exist, Django will raise a ``ValueError``. Finally, note that you'll probably want to keep a normal (non-site-specific) ``Manager`` on your model, even if you use @@ -379,7 +401,7 @@ Here's how Django uses the sites framework: :class:`~django.contrib.sites.models.Site` name to the template as ``{{ site_name }}``. -* The shortcut view (:func:`django.views.defaults.shortcut`) uses the domain +* The shortcut view (``django.views.defaults.shortcut``) uses the domain of the current :class:`~django.contrib.sites.models.Site` object when calculating an object's URL. @@ -387,6 +409,7 @@ Here's how Django uses the sites framework: :class:`~django.contrib.sites.models.Site` to work out the domain for the site that it will redirect to. +.. currentmodule:: django.contrib.sites.models ``RequestSite`` objects ======================= @@ -401,13 +424,26 @@ requires.) For those cases, the framework provides a :class:`~django.contrib.sites.models.RequestSite` class, which can be used as a fallback when the database-backed sites framework is not available. +.. class:: RequestSite + + A class that shares the primary interface of + :class:`~django.contrib.sites.models.Site` (i.e., it has + ``domain`` and ``name`` attributes) but gets its data from a Django + :class:`~django.http.HttpRequest` object rather than from a database. + + The ``save()`` and ``delete()`` methods raise ``NotImplementedError``. + + .. method:: __init__(request) + + Sets the ``name`` and ``domain`` attributes to the value of + :meth:`~django.http.HttpRequest.get_host`. + + A :class:`~django.contrib.sites.models.RequestSite` object has a similar interface to a normal :class:`~django.contrib.sites.models.Site` object, except its :meth:`~django.contrib.sites.models.RequestSite.__init__()` method takes an :class:`~django.http.HttpRequest` object. It's able to deduce the -:attr:`~django.contrib.sites.models.RequestSite.domain` and -:attr:`~django.contrib.sites.models.RequestSite.name` by looking at the -request's domain. It has :meth:`~django.contrib.sites.models.RequestSite.save()` -and :meth:`~django.contrib.sites.models.RequestSite.delete()` methods to match -the interface of :class:`~django.contrib.sites.models.Site`, but the methods -raise :exc:`NotImplementedError`. +``domain`` and ``name`` by looking at the request's domain. It has ``save()`` +and ``delete()`` methods to match the interface of +:class:`~django.contrib.sites.models.Site`, but the methods raise +``NotImplementedError``.