diff options
| -rw-r--r-- | docs/source/commands.rst | 13 | ||||
| -rw-r--r-- | docs/source/configuration.rst | 10 | ||||
| -rw-r--r-- | docs/source/deployment.rst | 2 | ||||
| -rw-r--r-- | docs/source/forms.rst | 5 | ||||
| -rw-r--r-- | docs/source/hooks.rst | 47 | ||||
| -rw-r--r-- | docs/source/index.rst | 49 | ||||
| -rw-r--r-- | docs/source/quick_start.rst | 10 | ||||
| -rw-r--r-- | docs/source/rest.rst | 12 | ||||
| -rw-r--r-- | docs/source/routing.rst | 8 | ||||
| -rw-r--r-- | docs/source/templates.rst | 8 | ||||
| -rw-r--r-- | docs/source/testing.rst | 4 |
11 files changed, 90 insertions, 78 deletions
diff --git a/docs/source/commands.rst b/docs/source/commands.rst new file mode 100644 index 0000000..3218888 --- /dev/null +++ b/docs/source/commands.rst @@ -0,0 +1,13 @@ +.. _commands: + +Command Line Pecan +================== +TODO + +Serving Pecan App For Development +--------------------------------- +TODO + +The Interactive Shell +--------------------- +TODO diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 05e6f30..9822af1 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -111,11 +111,11 @@ And it would be accessible in `pecan.conf` as:: 'foo_bar_user' -Fully Valid Dictionaries ------------------------- +Dictionary Conversion +--------------------- In certain situations you might want to deal with keys and values, but in strict dictionary form. The ``Config`` object has a helper method for this purpose -that will return a dictionary representation of itself including nested values. +that will return a dictionary representation of itself, including nested values. Below is a representation of how you can access the ``as_dict`` method and what should return as a result (shortened for brevity): @@ -129,8 +129,8 @@ should return as a result (shortened for brevity): {'app': {'errors': {}, 'template_path': '', 'static_root': 'public', [...] -Prefixing Values ----------------- +Prefixing Dictionary Keys +------------------------- ``Config.as_dict`` allows you to pass an optional argument if you need to prefix the keys in the returned dictionary. This is a single argument in string form and it works like this (shortened for brevity): diff --git a/docs/source/deployment.rst b/docs/source/deployment.rst index 9894467..461d004 100644 --- a/docs/source/deployment.rst +++ b/docs/source/deployment.rst @@ -3,8 +3,6 @@ Deployment Recipes ================== -Deploying Pecan projects -======================== Deploying a pecan project can be accomplished in several ways. You may already be familiar with deployment methodologies for other Python projects, in which case, try that! Pecan doesn't deviate from the diff --git a/docs/source/forms.rst b/docs/source/forms.rst new file mode 100644 index 0000000..802f55e --- /dev/null +++ b/docs/source/forms.rst @@ -0,0 +1,5 @@ +.. _forms: + +Generating and Validating Forms +=============================== +TODO diff --git a/docs/source/hooks.rst b/docs/source/hooks.rst index 99052cb..d95e21e 100644 --- a/docs/source/hooks.rst +++ b/docs/source/hooks.rst @@ -19,8 +19,8 @@ Hooks allow you to execute code at key points throughout the life cycle of your * ``on_error``: called when a request generates an exception -Implementation --------------- +Implementating a Pecan Hook +--------------------------- In the below example, we will write a simple hook that will gather some information about the request and print it to ``stdout``. @@ -84,8 +84,8 @@ the app and browse the application from our web browser:: response: 200 OK -Included Pecan Hooks --------------------- +Hooks That Come with Pecan +-------------------------- Pecan includes some hooks in its core and are very simple to start using them away. This section will describe their different uses, how to configure them and examples of common scenarios. @@ -93,8 +93,8 @@ and examples of common scenarios. .. _requestviewerhook: RequestViewerHook ------------------ -This hooks is very useful for debugging purposes. It has access to every +''''''''''''''''' +This hook is useful for debugging purposes. It has access to every attribute the ``response`` object has plus a few others that are specific to the framework. @@ -103,23 +103,25 @@ There are two main ways that this hook can provide information about a request: #. Terminal or logging output (via an file-like stream like `stdout`) #. Custom header keys in the actual response. -By default, both outputs are on if they are not configured. +By default, both outputs are enabled. For the actual object reference, please see :ref:`pecan_hooks`. -Automatically Enabled ---------------------- -This hook can be automatically added to the application itself if a certain key -exists in the configuration used for the app. This key is:: +Enabling RequestViewerHook +.......................... +This hook can be automatically added to the application itself if a certain +key, ``requestviewer``, exists in the configuration used for the app, e.g.:: - requestviewer + app = {} + server = {} + requestviewer = {} It does not need to contain anything (could be an empty dictionary), and this is enough to force Pecan to load this hook when the WSGI application is created. -Configuration -------------- +Configuring RequestViewerHook +............................. There are a few ways to get this hook properly configured and running. However, it is useful to know that no actual configuration is needed to have it up and running. @@ -137,7 +139,7 @@ No configuration will show those values in the terminal via `stdout` and it will also add them to the response headers (in the form of `X-Pecan-item_name`). -This is how the terminal output look for a `/favicon.ico` request :: +This is how the terminal output might look for a `/favicon.ico` request :: path - /favicon.ico status - 404 Not Found @@ -146,10 +148,9 @@ This is how the terminal output look for a `/favicon.ico` request :: params - [] hooks - ['RequestViewerHook'] -In the above case, the file was not found, and the information was properly -gathered and returned via `stdout`. - -And this is how those same values would be seen in the response headers:: +In the above case, the file was not found, and the information was printed to +`stdout`. Additionally, the following headers would be present in the HTTP +response:: X-Pecan-path /favicon.ico X-Pecan-status 404 Not Found @@ -177,8 +178,8 @@ And the same configuration could be set in the config file like:: requestviewer = {'items:['path']} -Specifying items ----------------- +Modifying Output Format +....................... Items are the actual information objects that the hook will use to return information. Sometimes you will need a specific piece of information or a certain bunch of them according to the development need so the defaults will @@ -248,8 +249,8 @@ And these are the specific ones from Pecan and the hook: * params (params is actually available from `webob` but it is parsed by the hook for redability) -Blacklisting ------------- +Blacklisting Certain Paths +.......................... Sometimes it's annoying to get information about *every* single request. For this purpose, there is a matching list of url paths that you can pass into the hook so that paths that do not match are returned. diff --git a/docs/source/index.rst b/docs/source/index.rst index f005387..86bfebc 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,28 +1,3 @@ -Pecan Documentation -=================== - -A WSGI object-dispatching web framework, designed to be lean and fast, -with few dependancies. - - -Contents: - -.. toctree:: - :maxdepth: 2 - - installation.rst - quick_start.rst - commands.rst - routing.rst - configuration.rst - templates.rst - rest.rst - secure_controller.rst - jsonify.rst - hooks.rst - testing.rst - - Introduction and History ======================== Welcome to Pecan, a lean Python web framework inspired by CherryPy, @@ -51,11 +26,31 @@ box, tutorials are included for integrating these yourself in just a few lines of code. -Cookbook -======== +Narrative Documentation +======================= + +.. toctree:: + :maxdepth: 2 + + installation.rst + quick_start.rst + commands.rst + routing.rst + templates.rst + rest.rst + configuration.rst + secure_controller.rst + jsonify.rst + hooks.rst + testing.rst + + +Cookbook and Common Patterns +============================ .. toctree:: :maxdepth: 2 + forms.rst sessions.rst databases.rst deployment.rst diff --git a/docs/source/quick_start.rst b/docs/source/quick_start.rst index f2ff1f0..4a29b56 100644 --- a/docs/source/quick_start.rst +++ b/docs/source/quick_start.rst @@ -1,7 +1,7 @@ .. _quick_start: -Quick Start -=========== +Creating Your First Pecan Application +===================================== Let's create a small sample project with Pecan. @@ -83,7 +83,7 @@ configuration file. .. _running_application: -Running the application +Running the Application ----------------------- Before starting up your Pecan app, you'll need a configuration file. The base project template should have created one for you already, ``config.py``. @@ -148,8 +148,8 @@ For more specific documentation on configuration, see the :ref:`Configuration` section. -Root Controller ---------------- +The Application Root +-------------------- The Root Controller is the root of your application. This is how it looks in the project template diff --git a/docs/source/rest.rst b/docs/source/rest.rst index 20447c3..75134d9 100644 --- a/docs/source/rest.rst +++ b/docs/source/rest.rst @@ -1,7 +1,7 @@ .. _rest: -REST Controller -=============== +Writing RESTful Web Services with Pecan +======================================= If you need to write controllers to interact with objects, using the ``RestController`` may help speed things up. It follows the Representational @@ -63,8 +63,8 @@ The ``RestController`` still supports the ``index``, ``_default``, and make sure to call ``RestController._route`` at the end of your custom ``_route`` method so that the REST routing described above still occurs. -Nesting -------- +Nesting ``RestController`` +--------------------------- ``RestController`` instances can be nested so that child resources get the parameters necessary to look up parent resources. For example:: @@ -110,8 +110,8 @@ parent controller. If the parent resource takes a variable number of arguments, Pecan will hand it everything up to the child resource controller name (e.g., ``books`` in the above example). -Custom Actions --------------- +Defining Custom Actions +----------------------- In addition to the default methods defined above, you can add additional behaviors to a ``RestController`` by defining a special ``_custom_actions`` diff --git a/docs/source/routing.rst b/docs/source/routing.rst index 498383f..e6025df 100644 --- a/docs/source/routing.rst +++ b/docs/source/routing.rst @@ -122,8 +122,8 @@ Please see :ref:`pecan_decorators` for more information on ``@expose``. -Routing Algorithm ------------------ +Pecan's Routing Algorithm +------------------------- Sometimes, the standard object-dispatch routing isn't adequate to properly route a URL to a controller. Pecan provides several ways to short-circuit @@ -209,8 +209,8 @@ top of Pecan, defining a base controller class that defines a ``_route`` method will enable you to have total control. -Controller Arguments --------------------- +Mapping Controller Arguments +---------------------------- In Pecan, HTTP ``GET`` and ``POST`` variables that are `not` consumed during the routing process can be passed onto the controller as arguments. diff --git a/docs/source/templates.rst b/docs/source/templates.rst index 8f8357c..b0d9407 100644 --- a/docs/source/templates.rst +++ b/docs/source/templates.rst @@ -25,8 +25,8 @@ The available renderer type strings are `mako`, `genshi`, `kajiki`, `jinja`, and `json`. -Using Renderers ---------------- +Using Template Renderers +------------------------ :ref:`pecan_decorators` defines a decorator called ``@expose``, which is used to flag a method as a controller. The ``@expose`` decorator takes a variety of @@ -81,8 +81,8 @@ more information on using `JSON` in Pecan, please refer to :ref:`jsonify` and :ref:`pecan_jsonify`. -Custom Renderers ----------------- +Defining Custom Renderers +------------------------- To define a custom renderer, you can create a class that follows a simple protocol:: diff --git a/docs/source/testing.rst b/docs/source/testing.rst index 20a13bc..99f1fab 100644 --- a/docs/source/testing.rst +++ b/docs/source/testing.rst @@ -1,5 +1,5 @@ .. _testing: -Unit Testing -============= +Writing Tests For Pecan Apps +============================ TODO |