Upgraded the documentation

README.rst

@@ -0,0 +1,60 @@
+
+grokcore.startup
+****************
+
+This package provides elements for starting a Grok project with
+paster and WSGI.
+
+That sounds simple but there is a huge amount going on under the hood.  
+
+WSGI stands for Web Server Gateway Interface.  It provides for a standard 
+way for any web server (including ones written in Python) 
+to talk to any Python application.  
+
+WSGI also allows one  to create 
+middleware, these are python applications which speak 
+WSGI on both the client and server sides.  
+Existing WSGI Middleware include logging, exception handling, and html validators. 
+It is also possible to chain together a web server, WSGI middleware, and a 
+Python application server.  Or one can even use middleware to 
+call  different Python application servers depending on the URL. 
+
+Okay that explains WSGI.  So how do we manage WSGI servers?  WIth Python software called Paste, PasteScript, and PasteDeploy.  This is where grokcore.startup comes in.  It does all the work to invoke and configure  the Paste routines. 
+
+To learn more about the WSGI 
+standard, I encourage you to read 
+`PEP 3333 <https://www.python.org/dev/peps/pep-3333/#abstract>`_
+It is very nicely written. 
+
+
+To learn more about Python Paste 
+standard, you might find the
+`Read the Docs  page <https://paste.readthedocs.io/en/latest/>`_
+helpful.
+
+And of course it is very helpful to read the 
+`grokcore.startup <./src/grokcore/startup/README.rst>`_ documentation.
+
+
+And if all of that still does not solve your problems, 
+there is great detailed documentation over at the  
+`Pyramid Pages on PasteDeploy <https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/paste.html>`_.
+They are the ones who reminded me to run:
+
+
+python setup.py develop
+
+
+Setting up ``grokcore.startup``
+===============================
+
+There is nothing special to setup this package.
+
+All you have to do is, to make this package available during runtime.
+
+With zc.buildout or other setuptools-related setups this can be
+done by simply adding the package name grokcore.startup to the
+required packages of your project in setup.py.
+
+
+

setup.py

@@ -5,9 +5,9 @@ def read(*rnames):
     return open(os.path.join(os.path.dirname(__file__), *rnames)).read()
 
 long_description = (
-    read('README.txt')
+    read('README.rst')
     + '\n' +
-    read(os.path.join('src', 'grokcore', 'startup', 'README.txt'))
+    read(os.path.join('src', 'grokcore', 'startup', 'README.rst'))
     + '\n' +
     read('CHANGES.txt')
     )

src/grokcore/startup/README.txt → src/grokcore/startup/README.rst

@@ -5,28 +5,10 @@ Setting up Grok projects as ``paster`` served WSGI applications
 ===============================================================
 
 The main target of this package is to provide support for enabling
-`Grok`_ applications to be run as `paster`_ served `WSGI`_
+`Grok`_ applications to be run as `paster`_ served `WSGI
 applications. To make this working some configuration files have to be
 set up.
 
-Setting up a project with ``grokproject``
------------------------------------------
-
-The most convenient way to setup a `Grok`_ project is using
-`grokproject`_. Once installed, you can a project like this::
-
-  $ grokproject Sample
-
-which will generate all configuration files for you.
-
-.. note:: Older versions of `grokproject`_ need an update
-
-  As older versions of `grokproject`_ do not support
-  `grokcore.startup`, you might want to update your existing
-  `grokproject`_ installation by running::
-
-    $ easy_install -U grokproject
-
 
 Setting up a project manually
 -----------------------------
@@ -48,7 +30,7 @@ several configuration files in the project root:
   ``parts/etc/`` subdirectory of your `Grok`_ project)
 
 
-When we want to setup a Zope instance as `paster`_ served `WSGI`_
+When we want to setup a Zope instance as paster served WSGI
 application, then we have to set a ``paste.app_factory`` entry point
 in ``setup.py``. A minimal setup could look like this::
 
@@ -70,11 +52,19 @@ in ``setup.py``. A minimal setup could look like this::
         include_package_data=True,
         zip_safe=False,
         install_requires=['setuptools',],
-        entry_points = """
-        [paste.app_factory]
-        main = grokcore.startup:application_factory
-        """,
-        )
+        entry_points={
+            'paste.app_factory': [
+               'main = grokcore.startup:application_factory',
+               'debug = grokcore.startup:debug_application_factory',
+               ],
+
+             #YOU WILL PROBABLY  ALSO WANT FANSTATIC
+             #'fanstatic.libraries': [
+             #    'zopache = zopache.resource:library',
+             #     ],
+
+        },
+  )
 
 Here the `paste.app_factory` entry point pointing to
 `grokcore.startup:application_factory` is important.
@@ -132,20 +122,25 @@ where the ``site-definition`` entry should point to the location of
 the file ``site.zcml``. In regular Grok projects those files are put
 into the ``etc/`` subdirectory of your project root.
 
-Finally we have to provide a ``deploy.ini`` (or another .ini-file),
+Finally we have to provide a ``deploy.ini``  and ``debug.ini`` 
 which tells paster where to find the pieces. This is also put into the
 ``etc/`` subdirectory of your project root in regular Grok projects
-created by `grokproject`_::
+created by grokproject:
 
   [app:main]
+
   use = egg:sampleproject
 
   [server:main]
+
   use = egg:Paste#http
+
   host = 127.0.0.1
+
   port = 8080
 
   [DEFAULT]
+
   zope_conf = %(here)s/zope.conf
 
 
@@ -157,11 +152,11 @@ API Documentation
 --------------------------------------------------
 
   ``grokcore.startup`` provides a function ``application_factory``
-  which delivers a `WSGIPublisherApplication`_ instance when called
+  which delivers a WSGIPublisherApplication instance when called
   with an appropriate configuration. See the `zope.app.wsgi
   documentation
   <http://apidoc.zope.org/++apidoc++/Code/zope/app/wsgi/README.txt/index.html>`_
-  to learn more about Zope objects supporting `WSGI`_.
+  to learn more about Zope objects supporting WSGI.
 
   A call to this function is normally required as entry point in
   `setuptools`_-driven `paster`_ environments  (see