Permalink
Browse files

Add settings management API doc; update other pages to refer to it wh…

…ere appropriate.
  • Loading branch information...
1 parent 5fcd17e commit 1abbe354959fa305106196d452e565e05d12e8a8 @rfreebern rfreebern committed Jun 14, 2012
Showing with 50 additions and 17 deletions.
  1. +5 −0 getting-started/installation.rst
  2. +5 −17 getting-started/upgrading.rst
  3. +1 −0 userguide/index.rst
  4. +39 −0 userguide/settings.rst
@@ -78,6 +78,11 @@ You can now view the dev server at http://localhost:8000/ -- hooray!
If you start adding pieces that should go back into playdoh, you will probably
want to patch `funfactory`_, which is the core of Playdoh.
+If your app's configuration requires you to add or remove apps, middleware, or
+template context processors from the default funfactory configuration, you can
+use the ``get_apps``, ``get_middleware``, and ``get_context_processors``
+functions. See the :ref:`settings management API <settings>` documentation.
+
.. _funfactory: https://github.com/mozilla/funfactory
.. _`MySQL`: http://www.mysql.com/
@@ -39,33 +39,19 @@ Applying Playdoh to an existing Django app is a little different than
to::
- INSTALLED_APPS = list(INSTALLED_APPS) + [...]
+ INSTALLED_APPS = get_apps(append=(...))
Do the same for any other lists which have been customized.
This will ensure that you inherit the default funfactory settings.
- You can remove any entries in ``INSTALLED_APPS`` from your ``settings.py``
- if they are already in ``funfactory.settings_base.py`` by using the utility
- function ``get_apps`` from funfactory's ``utils.py``::
@kumar303

kumar303 Jun 14, 2012

Member

If you turn on autodoc (below) then you can do :func:get_apps`` and it will create a link directly to the signature definition of each function.

-
- from funfactory.utils import get_apps
-
- INSTALLED_APPS = get_apps(exclude=(
- 'django.contrib.auth',
- 'django_sha2'
- ))
-
- Similar functions ``get_middleware`` and ``get_template_context_processors``
- exist to help manage ``MIDDLEWARE_CLASSES`` and
- ``TEMPLATE_CONTEXT_PROCESSORS`` respectively.
+ See the :ref:`settings management API <settings>` for information about
+ funfactory's built-in settings management functions, including ``get_apps``.
#. You can remove any redundant settings in ``settings.py`` if they appear in
``funfactory.settings_base``.
.. _`funfactory from PyPI`: http://pypi.python.org/pypi/funfactory
-.. _manual-upgrae:
-
Mind those monkey patches
-------------------------
@@ -80,6 +66,8 @@ See the :ref:`Monkey patches <monkeypatches>` documentation for the
lines you need to add to your root urls.py if you don't already have
them.
+.. _manual-upgrade:
+
Manual upgrade
--------------
View
@@ -15,3 +15,4 @@ User Guide
logging
template-context
errors
+ settings
View
@@ -0,0 +1,39 @@
+.. _settings:
+
+=======================
+Settings Management API
+=======================
+
+Funfactory's default settings module provides some useful helper functions that
+make managing your playdoh app's settings easier.
@kumar303

kumar303 Jun 14, 2012

Member

by magic, if you put these lines, the docs will be built from the docstrings of each function:

.. autofunction:: funfactory.settings_base.get_apps

.. autofunction:: funfactory.settings_base.get_middleware

.. autofunction:: funfactory.settings_base.get_template_context_processors

We might have to turn autodoc on in docs/conf.py

@rfreebern

rfreebern Jun 14, 2012

Contributor

I tried to use autodoc but it wanted to actually import settings_base from funfactory, which depends on all sorts of other stuff. At some point it felt impractical to keep trying to get that working rather than just write it myself.

@kumar303

kumar303 Jun 14, 2012

Member

Try adding this to conf.py:

import os
from funfactory import manage
manage.setup_environ(os.path.join(os.path.dirname(__file__), '..', 'manage.py'), more_pythonic=True)

That should put vendor on the path and everything else you need. You may also need os.environ('DJANGO_SETTINGS_MODULE', 'project.settings') but try it first without

+
+* ``get_apps(exclude=(), append=())``
+
+ The ``get_apps`` function returns the current INSTALLED_APPS tuple, modified
+ based on the ``exclude`` and ``append`` parameters, which can be tuples or
+ lists. INSTALLED_APPS originates in funfactory's ``settings_base.py`` file,
+ containing the default suite of funfactory apps, but can be modified using
+ this function to add or remove apps as necessary for your project.
+
+ The state of the INSTALLED_APPS tuple returned by this function persists so
+ that you can modify it as necessary for your app in ``settings/base.py``
+ and then further modify it for your local install in ``settings/local.py``.
+
+ Example::
+
+ INSTALLED_APPS = get_apps(
+ exclude=('cronjobs', 'djcelery'),
+ append=('debug_toolbar',)
+ )
@kumar303

kumar303 Jun 14, 2012

Member

You can move this (reST formatting and all) to the docstring after autodoc'ing

+
+* ``get_middleware(exclude=(), append=())``
+
+ Similar to ``get_apps``, this function returns the current
+ MIDDLEWARE_CLASSES tuple and persists its state through the various
+ settings files.
+
+* ``get_template_context_processors(exclude=(), append=())``
+
+ Again, similar to ``get_apps`` but returns the current
+ TEMPLATE_CONTEXT_PROCESSORS tuple and persists its state through the various
+ settings files.

0 comments on commit 1abbe35

Please sign in to comment.