From e0887ee8690ab6189fc5c2e0814e4f537f0a2180 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 31 Dec 2009 14:31:49 +0000 Subject: De-stiltify. --- docs/glossary.rst | 4 +++ docs/narr/configuration.rst | 67 +++++++++++++++++++++++---------------------- docs/narr/introduction.rst | 55 ++++++++++++++++++++++++------------- 3 files changed, 75 insertions(+), 51 deletions(-) diff --git a/docs/glossary.rst b/docs/glossary.rst index d87b2f990..e649b3498 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -616,3 +616,7 @@ Glossary PyPI `The Python Package Index `_, a collection of software available for Python. + + Agendaless Consulting + A consulting organization formed by Paul Everitt, Tres Seaver, + and Chris McDonough. See also http://agendaless.com . diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst index 0584e8671..edb3950e3 100644 --- a/docs/narr/configuration.rst +++ b/docs/narr/configuration.rst @@ -1,56 +1,59 @@ +.. index:: + single: frameworks vs. libraries + single: framework + .. _configuration_narr: Creating Your First :mod:`repoze.bfg` Application ================================================= -The majority of the logic in any web application is completely +Most of the logic in a web application is completely application-specific. For example, the content of a web page served by one web application might be a representation of the contents of an accounting ledger, while the content of of a web page served by -another might be a listing of songs. These applications obviously -will not serve the same set of customers. However, both the +another might be a listing of songs. These applications probably +won't serve the same set of customers. However, both the ledger-serving and song-serving applications can be written using :mod:`repoze.bfg`, because :mod:`repoze.bfg` is a very general *framework* which can be used to create all kinds of web applications. +As a framework, the primary job of :mod:`repoze.bfg` is to make it +easier for a developer to create an arbitrary web application. .. sidebar:: Frameworks vs. Libraries A *framework* differs from a *library* in one very important way: library code is always *called* by code that you write, while a framework always *calls* code that you write. Using a set of - libraries to create an application is often initially easier than - using a framework to create an application, because the developer - can choose to cede control to library code he has not authored - selectively. When using a framework, the developer is typically - required to cede a greater portion of control to code he has not - authored: code that resides in the framework itself. You needn't - use a framework at all to create a web application using Python. A - rich set of libraries already exists for the platform. In - practice, however, using an existing framework to create an - application is often more practical than rolling your own via a set - of libraries if the framework provides a set of facilities and - assumptions that fit your application requirements. - -As a framework, the primary job of :mod:`repoze.bfg` is to make it -easier for a developer to create an arbitrary web application. Each -deployment of an application written using :mod:`repoze.bfg` implies a -specific *configuration* of the framework itself. For example, a -song-serving application might plug code into the framework that -manages songs, while the ledger- serving application might plug in -code that manages accounting information. :mod:`repoze.bfg` refers to -the way in which code is plugged in to it for a specific deployment as -"configuration". + libraries to create an application is usually easier than using a + framework initially, because you can choose to cede control to + library code you have not authored very selectively. But when you + use a framework, you are required to cede a greater portion of + control to code you have not authored: code that resides in the + framework itself. You needn't use a framework at all to create a + web application using Python. A rich set of libraries already + exists for the platform. In practice, however, using a framework + to create an application is often more practical than rolling your + own via a set of libraries if the framework provides a set of + facilities that fits your application requirements. + +Each deployment of an application written using :mod:`repoze.bfg` +implies a specific *configuration* of the framework itself. For +example, a song-serving application might plug code into the framework +that manages songs, while the ledger- serving application might plug +in code that manages accounting information. :mod:`repoze.bfg` refers +to the way in which code is plugged in to it for a specific +application as "configuration". Most people understand "configuration" as coarse knobs that inform the high-level operation of a specific application deployment. For instance, it's easy to think of the values implied by a ``.ini`` file which is parsed at application startup time as "configuration". -:mod:`repoze.bfg` extends this pattern all the way out to application -development, using the term "configuration" to express standardized -methods which can be used to plug code into a deployment of the -framework itself. When you plug code into the :mod:`repoze.bfg` -framework, you are indeed "configuring" :mod:`repoze.bfg` for the -purpose of creating a particular application deployment. +:mod:`repoze.bfg` extends this pattern out to application development, +using the term "configuration" to express standardized ways that code +gets plugged into a deployment of the framework itself. When you plug +code into the :mod:`repoze.bfg` framework, you are "configuring" +:mod:`repoze.bfg` for the purpose of creating a particular application +deployment. There are a number of different mechanisms you may use to configure :mod:`repoze.bfg` to create an application: *imperative* configuration @@ -67,7 +70,7 @@ Hello World, Configured Imperatively Experienced Python programmers may find the "imperative" configuration mechanism fits the way they already do things. This is the -configuration mode in which developers cede the least amount of +configuration mode in which a developer cedes the least amount of control to the framework. It is often the easiest configuration mode to understand. diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 497b09b40..898b67655 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -1,3 +1,9 @@ +.. index:: + single: Agendaless Consulting + single: Pylons + single: Django + single: Zope + :mod:`repoze.bfg` Introduction ============================== @@ -5,12 +11,10 @@ It is inspired by :term:`Zope`, :term:`Pylons`, and :term:`Django`. It uses the :term:`WSGI` protocol to handle requests and responses. -:mod:`repoze.bfg` is written by Agendaless Consulting and a community -of contributors. It is developed primarily by people who come from -the world of :term:`Zope` but for whom Zope as a web application -development platform has lost some of its attraction. Its authors -also have experience developing applications using many other web -frameworks. +:mod:`repoze.bfg` is written by :term:`Agendaless Consulting` and a +community of contributors. It is developed primarily by people who +come from the world of :term:`Zope`. Its authors also have experience +developing applications using many other web frameworks. The first release of :mod:`repoze.bfg` was made in July of 2008. Since its first release, it has undergone many improvements, and has @@ -19,14 +23,16 @@ attributes: Simplicity :mod:`repoze.bfg` attempts to be a *"pay only for what you eat"* - framework in which you can be productive quickly with partial - knowledge. We contrast this with *"pay up front for what anyone - might eventually want to eat"* frameworks, which tend to expect you - to understand a great many concepts and technologies fully before - you can be truly productive. :mod:`repoze.bfg` doesn't force you to - use any particular technology to produce an application, and we try - to keep the core set of concepts you need to understand to a - minimum. + framework in which you can be productive quickly with only partial + knowledge. Some other frameworks tend to expect you to understand a + great many concepts and technologies fully before you can be truly + productive. :mod:`repoze.bfg` doesn't force you to use any + particular technology to produce an application, and we try to keep + the core set of concepts you need to understand to a minimum. + +A Sense of Fun + Developing a :mod:`repoze.bfg` application should not feel + "enterprisey". We like to keep things down-to-earth. Minimalism :mod:`repoze.bfg` provides only the very basics: *URL to code @@ -57,12 +63,13 @@ Trustability exhaustively. *If it ain't tested, it's broke.* Every release of :mod:`repoze.bfg` has 100% statement coverage via unit tests. -A Sense of Fun - Developing a :mod:`repoze.bfg` application should not feel foreign - or "enterprisey". We like to keep things down-to-earth. - .. index:: single: similarities to other frameworks + single: Grok + single: Zope + single: Pylons + single: Django + single: MVC Similarities to Other Web Frameworks ------------------------------------ @@ -114,10 +121,15 @@ would be by Django. The skeleton code generator of :mod:`repoze.bfg` generates a directory layout very similar to the directory layout suggested by the `Django -Book `_ . +Book `_ . .. index:: single: differences from other frameworks + single: Grok + single: Zope + single: Pylons + single: Django + single: control inversion Differences from Other Web Frameworks ------------------------------------- @@ -174,6 +186,11 @@ relational database. :mod:`repoze.bfg` makes no such assumption; it allows you to use a relational database but doesn't encourage or discourage an application developer about such a decision. +.. index:: + single: Repoze + single: Agendaless Consulting + pair: repoze; namespace package + What Is Repoze? --------------- -- cgit v1.2.3