From 207f8d42b9e1357b5bb82c87f1f5d9360c0861d8 Mon Sep 17 00:00:00 2001 From: Ian Bicking Date: Fri, 30 Sep 2005 23:15:08 +0000 Subject: Changed front page, with different entry points and documentation --- docs/develop-example.txt | 72 ++++++++++++++++++++++++ docs/developer-features.txt | 131 ++++++++++++++++++++++++++++++++++++++++++++ docs/enabled.txt | 4 ++ docs/index.txt | 50 +++++++++++++++++ docs/install-example.txt | 33 +++++++++++ setup.cfg | 3 + 6 files changed, 293 insertions(+) create mode 100644 docs/develop-example.txt create mode 100644 docs/developer-features.txt create mode 100644 docs/enabled.txt create mode 100644 docs/install-example.txt diff --git a/docs/develop-example.txt b/docs/develop-example.txt new file mode 100644 index 0000000..efc871b --- /dev/null +++ b/docs/develop-example.txt @@ -0,0 +1,72 @@ +Development With Paste: An Example +++++++++++++++++++++++++++++++++++ + +This example uses `WebKit `_, `SQLObject +`_, and `Zope Page Templates <>`_, but it's all +pluggable for other frameworks and tools. + +Paste enabled applications are all proper Python packages, and even +moreso they are installable by `easy_install <>`_, including Paste +itself:: + + $ easy_install PasteScript PasteWebKit SQLObject ZPTKit + ... messages fly by ... + +This example also uses Subversion repository (we'll assume you've set +up a repository with ``svnadmin create /home/me/testrepos``). When +you create a project, you can create a layout in your repository for +it. + +This will create the new project:: + + $ paster create --template=webkit --template=zpt \ + --svn-repository=file:///home/me/testrepos Wiki + ... the package is setup in the repository ... + ... file listings fly by ... + $ cd Wiki + $ svn commit -m "New project" + ... messages about committing ... + +The basic setup has a simplest of applications already set up; you can +test everything is working by running:: + + $ paster serve --reload docs/devel_config.ini + ... now your new app is served on http://localhost:8080/ ... + ... ^C to quit + +It also has set up a `py.test <>`_ fixture for you, so you can run the +first test (which just tests that the front page loads up properly): + + $ py.test -v + ... test results ... + +Using the ``webkit`` template we've also added a new command for +setting up new servlets:: + + $ paster servlet listing + ... @@: creating files ... + +Also, all the metadata for SQLObject has been added to the template, +and can be used like:: + + $ sqlobject-admin create --egg=Wiki + ... database create statements ... + +You can add version information to your model as well, so that you can +develop and record your updates, and then apply them to old versions +of the database. + +Once you've made something you are ready to deploy, you can use +`buildutils <>`_ to tag it for release:: + + $ python setup.py svntag --version=0.1 -b ../Wiki01 + $ cd ../Wiki01 + $ python setup.py sdist + ... boring messages ... + ... @@: Deploy stuff ... + +And then deploy it on another server:: + + $ ssh other-server + ... @@: More deploy stuff ... + diff --git a/docs/developer-features.txt b/docs/developer-features.txt new file mode 100644 index 0000000..bc08010 --- /dev/null +++ b/docs/developer-features.txt @@ -0,0 +1,131 @@ +Documentation +============= + +Tutorials and Introduction +========================== + +* `To-Do Tutorial `_ + +The core Paste package is a set of tools that use `WSGI +`_ heavily as the means of +communication. WSGI is an in-process CGI-like communication protocol. + +Right now the best way to see the various tools available in Paste is +to `look through the source `_. + +Related Projects +================ + +Closely related packages: + +* `Paste Deploy `_ +* `Paste Script `_ +* `Paste WebKit `_ +* `Wareweb `_ + +Developer Documentation +======================= + +* `Developer Guidelines `_ +* `Style Guide `_ + +Reference Documentation +======================= + +* `Testing Applications With Paste `_ +* `URL Parsing with WSGI and Paste `_ + + +License +======= + +Paste is distributed under the `Python Software Foundation`__ +license. This is a BSD/MIT-style license. + +.. __: http://www.python.org/psf/license.html + +Overview +======== + +If you don't want to look through source, here's a quick overview of +what there is here: + +Testing +------- + +* A fixture for testing WSGI applications conveniently and in-process, + in ``paste.fixture`` + +* A fixture for testing command-line applications, also in + ``paste.fixture`` + +* Check components for WSGI-compliance in ``paste.lint`` + +Dispatching +----------- + +* Chain and cascade WSGI applications (returning the first non-error + response) in ``paste.cascade`` + +* Dispatch to several WSGI applications based on URL prefixes, in + ``paste.urlmap`` + +* Allow applications to make subrequests and forward requests + internally, in ``paste.recursive`` + +Web Application +--------------- + +* Run CGI programs as WSGI applications in ``paste.cgiapp`` (and + Python-sepcific CGI programs with ``paste.pycgiwrapper``) + +* Traverse files and load WSGI applications from ``.py`` files (or + static files), in ``paste.urlparser`` + +* Serve static directories of files, also in ``paste.urlparser`` + +Tools +----- + +* Catch HTTP-related exceptions (e.g., ``HTTPNotFound``) and turn them + into proper responses in ``paste.httpexceptions`` + +* Check for signed cookies for authentication, setting ``REMOTE_USER`` + in ``paste.login`` + +* Create sessions in ``paste.session`` and ``paste.flup_session`` + +* Gzip responses in ``paste.gzip`` + +* A wide variety of routines for manipulating WSGI requests and + producing responses, in ``paste.wsgilib`` + +Debugging Filters +----------------- + +* Catch (optionally email) errors with extended tracebacks (using + Zope/ZPT conventions) in ``paste.exceptions`` + +* Catch errors presenting a `cgitb + `_-based + output, in ``paste.cgitb_catcher``. + +* Profile each request and append profiling information to the HTML, + in ``paste.profilemiddleware`` + +* Capture ``print`` output and present it in the browser for + debugging, in ``paste.printdebug`` + +* Validate all HTML output from applications using the `WDG Validator + `_, appending any errors + or warnings to the page, in ``paste.wdg_validator`` + +Other Tools +----------- + +* A file monitor to allow restarting the server when files have been + updated (for automatic restarting when editing code) in + ``paste.reloader`` + +* A class for generating and traversing URLs, and creating associated + HTML code, in ``paste.url`` diff --git a/docs/enabled.txt b/docs/enabled.txt new file mode 100644 index 0000000..db2f2e9 --- /dev/null +++ b/docs/enabled.txt @@ -0,0 +1,4 @@ +Paste Enabled ++++++++++++++ + +... what does it mean ... diff --git a/docs/index.txt b/docs/index.txt index bc08010..710c873 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -1,3 +1,53 @@ +Python Paste +============ + +Python Paste -- 50% tastier than Elmer's! +Paste: making the web sticky. +Fix broken websites by applying a Paste liberally. +Paste: paper over your inconsistencies. +Paste: a soft mixture of malleable consistency. +Paste: a tasty mixture to be spread on bread or crackers. +Paste: the glue that won't hurt you when you eat it. +Python Paste: the web extruded into the form of a snake. +Paste: the vinegar eel. +Paste: you bring the cut. +Paste: a doughy substance from which to make metaphorical web cupcakes. + +Python Paste brings consistency to Python web development and web +application installation, providing tools for both developers and +system administrators. + +Paste for Administrators +------------------------ + +* Easily install, run, and configure multiple Paste-enabled web + applications at once, and integrate them into your website how you + want (SCGI, FCGI, AJP, WSGI) + +* Manage and install web applications system-wide for easy maintenance + +* `See an installation example `_ or `read more + about what Paste-enabled means... `_ + +Paste for Web Developers +------------------------ + +* Increase your web application's audience + +* Provide starter templates and custom commands for using your web + framework + +* Keep your development and deployment straightened out, and your + automated testing streamlined + +* Attention payed to the full development cycle -- starting projects, + converting old projects, updating and deploying projects -- using a + set of `complimentary packages and tools `_ + +* `See a development example `_ or `read more + about using Paste in your + applications... `_ + Documentation ============= diff --git a/docs/install-example.txt b/docs/install-example.txt new file mode 100644 index 0000000..4024f0d --- /dev/null +++ b/docs/install-example.txt @@ -0,0 +1,33 @@ +Paste Installation +++++++++++++++++++ + +Installation of Paste-enabled applications is consistent and reliable; +you don't have to understand what technologies those applications +used. Paste-enabled applications are installable with `easy_install +<>`_, like:: + + $ easy_install FileBrowser + ... messages ... + +Once an application is installed, you can set up an instance of that +application with ``paste deploy``:: + + $ paste deploy FileBrowser location + ... @@: make this work ;) ... + +This just wrote to ``location/filebrowser.ini`` -- you can configure +the application there, with whatever specifics that application needs. +Then you can integrate it into your website and other applications, +with a file like:: + + [composit:main] + use = egg:Paste#urlmap + /browser = config:filebrowser.ini + +You can attach applications to many locations using this. Once you've +set that file up with your local settings and preferences, you can +run:: + + $ paster serve location/apps.ini --daemon + +And it will be running in the background. diff --git a/setup.cfg b/setup.cfg index 8c87f4a..0ef5777 100644 --- a/setup.cfg +++ b/setup.cfg @@ -10,6 +10,9 @@ docs = docs/index.txt docs/DeveloperGuidelines.txt docs/StyleGuide.txt docs/community/index.txt docs/community/mailing-list.txt docs/community/repository.txt docs/download/index.txt + docs/develop-example.txt docs/developer-features.txt + docs/enabled.txt docs/install-example.txt + doc_base = docs/ dest = docs/html modules = paste -- cgit v1.2.1