From 04bee54e9b793790e8e612ccaa50547f1e440e9f Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 17 Jan 2010 17:28:30 +0000 Subject: Reduce overall book size by not giving each ZCML directive its own chapter. --- docs/api.rst | 31 ++++++++++++++++++++++++ docs/authorintro.rst | 56 ++++++++++++++++++++++++++++++-------------- docs/index.rst | 51 ++++++++++------------------------------ docs/latexindex.rst | 32 +++---------------------- docs/narr/contextfinding.rst | 6 ++--- docs/zcml.rst | 2 +- 6 files changed, 88 insertions(+), 90 deletions(-) create mode 100644 docs/api.rst (limited to 'docs') diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 000000000..2bd5fca01 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,31 @@ +API Documentation +================= + +Comprehensive reference material for every public API exposed by +:mod:`repoze.bfg` is available within this chapter. The API +documentation is organized alphabetically by module name. + +.. toctree:: + :maxdepth: 1 + + api/authorization + api/authentication + api/chameleon_text + api/chameleon_zpt + api/configuration + api/events + api/exceptions + api/interfaces + api/location + api/paster + api/router + api/scripting + api/security + api/settings + api/testing + api/threadlocal + api/traversal + api/url + api/view + api/wsgi + diff --git a/docs/authorintro.rst b/docs/authorintro.rst index 53d62834d..4355fc125 100644 --- a/docs/authorintro.rst +++ b/docs/authorintro.rst @@ -1,16 +1,17 @@ -Author Introduction -=================== +===================== + Author Introduction +===================== Welcome to "The :mod:`repoze.bfg` Web Application Framework". In this -introduction, I'll describe this book, I'll provide some context -regarding the genesis of :mod:`repoze.bfg`, and I'll thank some -important people. +introduction, I'll describe the audience for this book, I'll describe +the book content, I'll provide some context regarding the genesis of +:mod:`repoze.bfg`, and I'll thank some important people. I hope you enjoy both this book and the software it documents. I've had a blast writing both. Audience --------- +======== This book is aimed primarily at a reader that has the following attributes: @@ -44,17 +45,36 @@ structures. As a result, you can usually avoid becoming "blocked" while you read this book even if you don't yet deeply understand web technologies. -Book Style ----------- +.. index:: + single: book content overview + +Book Content +============ + +This book is divided into three major parts: a narrative documentation +part, a tutorial part, and an API documentation part. + +Narrative Documentation + + This is documentation which describes :mod:`repoze.bfg` concepts in + narrative form, written in a largely conversational tone. Each + narrative documentation chapter describes an isolated + :mod:`repoze.bfg` concept. You should be able to get useful + information out of the narrative chapters if you read them + out-of-order, or when you need only a reminder about a particular + topic while you're developing an application. + +Tutorials + + Each tutorial builds a sample application or implements a concept + and describes the concept in terms of the example. You should read + the tutorials if you want a guided tour of :mod:`repoze.bfg`. + +Reference -This book is not the kind of book that imposes upon the reader by -describing concepts in terms of a single manufactured sample -application; in particular, its narrative does not build a small -application into a larger one as the book progresses. As a result, -you should be able to get useful information out of the book if you -neglect to read it from cover-to-cover, if you read it out-of-order, -or when you need only a reminder about a particular topic while you're -developing an application. + The API documentation is reference material related to the + :mod:`repoze.bfg` API. Use it while you're developing a + :mod:`repoze.bfg` application. .. index:: single: repoze.zope2 @@ -62,7 +82,7 @@ developing an application. single: Zope 2 The Genesis of :mod:`repoze.bfg` --------------------------------- +================================ I wrote :mod:`repoze.bfg` after many years of writing applications using :term:`Zope`. Zope provided me with a lot of mileage: it wasn't @@ -109,7 +129,7 @@ a cohesive whole that is reliable, down-to-earth, flexible, speedy, and well-documented. Thanks ------- +====== This book is dedicated to my grandmother, Dorothy Phillips, who gave me my first typewriter (a Royal), and my mother, Donelle Duffy, who diff --git a/docs/index.rst b/docs/index.rst index 9535a2815..3f5f81cfd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -61,45 +61,6 @@ Narrative documentation in chapter form explaining how to use narr/router narr/threadlocals -API documentation -================= - -Per-module :mod:`repoze.bfg` API documentation. - -.. toctree:: - :maxdepth: 2 - - api/authorization - api/authentication - api/chameleon_text - api/chameleon_zpt - api/configuration - api/events - api/exceptions - api/interfaces - api/location - api/paster - api/router - api/scripting - api/security - api/settings - api/testing - api/threadlocal - api/traversal - api/url - api/view - api/wsgi - -ZCML Directives -=============== - -Documentation for each :mod:`repoze.bfg` :term:`ZCML directive`. - -.. toctree:: - :maxdepth: 1 - - zcml - Tutorials ========= @@ -119,6 +80,18 @@ applications to various platforms. tutorials/zodbsessions/index.rst tutorials/catalog/index.rst +Reference Material +================== + +Reference material includes API documentation and documentation of +every :mod:`repoze.bfg` :term:`ZCML directive`. + +.. toctree:: + :maxdepth: 2 + + api + zcml + Detailed Change History ======================= diff --git a/docs/latexindex.rst b/docs/latexindex.rst index 89563b779..4000ea077 100644 --- a/docs/latexindex.rst +++ b/docs/latexindex.rst @@ -62,39 +62,13 @@ Tutorials tutorials/zodbsessions/index.rst tutorials/catalog/index.rst -API documentation -@@@@@@@@@@@@@@@@@ - -.. toctree:: - :maxdepth: 2 - - api/authorization - api/authentication - api/chameleon_text - api/chameleon_zpt - api/configuration - api/events - api/exceptions - api/interfaces - api/location - api/paster - api/router - api/scripting - api/security - api/settings - api/testing - api/threadlocal - api/traversal - api/url - api/view - api/wsgi - -ZCML Directives -@@@@@@@@@@@@@@@@ +Reference material +@@@@@@@@@@@@@@@@@@ .. toctree:: :maxdepth: 1 + api zcml .. backmatter:: diff --git a/docs/narr/contextfinding.rst b/docs/narr/contextfinding.rst index 74d9e3cc5..a31d0dc19 100644 --- a/docs/narr/contextfinding.rst +++ b/docs/narr/contextfinding.rst @@ -24,9 +24,9 @@ finding` and :term:`view lookup`. the :mod:`repoze.bfg` view lookup subsystem is provided with a :term:`request`, a :term:`context` and a :term:`view name`. It is then responsible for finding and invoking a :term:`view callable`. - A view callable is a specific bit of code that receives the - :term:`request` and which returns a :term:`response`, written and - registered by the application developer. + A view callable is a specific bit of code written and registered by + the application developer which receives the :term:`request` and + which returns a :term:`response`. These two subsystems are are used by :mod:`repoze.bfg` serially: first, a :term:`context finding` subsystem does its job. Then the diff --git a/docs/zcml.rst b/docs/zcml.rst index be82741aa..995b1bed9 100644 --- a/docs/zcml.rst +++ b/docs/zcml.rst @@ -1,7 +1,7 @@ .. _zcml_directives: ZCML Directives ----------------- +=============== :term:`ZCML` is an XML dialect that may be used by a :mod:`repoze.bfg` application to perform :term:`declarative configuration`. Each -- cgit v1.2.3