diff --git a/docs/source/commands.rst b/docs/source/commands.rst index 1706fbe..cfcfbf7 100644 --- a/docs/source/commands.rst +++ b/docs/source/commands.rst @@ -28,27 +28,7 @@ described in :ref:`server_configuration`. Reloading Automatically as Files Change +++++++++++++++++++++++++++++++++++++++ - -Pausing to restart your development server as you work can be interruptive, so -``pecan serve`` provides a ``--reload`` flag to make life easier. - -To provide this functionality, Pecan makes use of the Python ``watchdog`` -library. You'll need to install it for development use before continuing:: - - $ pip install watchdog - Downloading/unpacking watchdog - ... - Successfully installed watchdog - -:: - - $ pecan serve --reload config.py - Monitoring for changes... - Starting server in PID 000. - serving on 0.0.0.0:8080, view at http://127.0.0.1:8080 - -As you work, Pecan will listen for any file or directory modification events in your project and silently restart your server process in the background. - +.. include:: reload.rst The Interactive Shell --------------------- diff --git a/docs/source/development.rst b/docs/source/development.rst index f34a3f2..f987ddf 100644 --- a/docs/source/development.rst +++ b/docs/source/development.rst @@ -1,12 +1,11 @@ .. _development: -The Pecan Development Environment -================================= -TODO: Special topics related to Pecan local development +Developing Pecan Applications Locally +===================================== Reloading Automatically as Files Change --------------------------------------- -TODO +.. include:: reload.rst Debugging Pecan Applications ---------------------------- @@ -14,4 +13,21 @@ TODO Serving Static Files -------------------- -TODO +Pecan comes with simple file serving middleware for serving CSS, Javascript, +images, and other static files. You can configure it by ensuring that the +following options are specified in your configuration file:: + + app = { + ... + 'debug': True, + 'static_root': '%(confdir)/public + } + +...where ``static_root`` is an absolute pathname to the directory in which your +static files live. For convenience, the path may include the ``%(confdir)`` +variable, which Pecan will substitute with the absolute path of your +configuration file at runtime. + +.. note:: + In production, ``app.debug`` should *never* be set to ``True``, so you'll + need to serve your static files via your production web server. diff --git a/docs/source/reload.rst b/docs/source/reload.rst new file mode 100644 index 0000000..4898e57 --- /dev/null +++ b/docs/source/reload.rst @@ -0,0 +1,19 @@ +Pausing to restart your development server as you work can be interruptive, so +``pecan serve`` provides a ``--reload`` flag to make life easier. + +To provide this functionality, Pecan makes use of the Python ``watchdog`` +library. You'll need to install it for development use before continuing:: + + $ pip install watchdog + Downloading/unpacking watchdog + ... + Successfully installed watchdog + +:: + + $ pecan serve --reload config.py + Monitoring for changes... + Starting server in PID 000. + serving on 0.0.0.0:8080, view at http://127.0.0.1:8080 + +As you work, Pecan will listen for any file or directory modification events in your project and silently restart your server process in the background. diff --git a/pecan/__init__.py b/pecan/__init__.py index 521d7ff..ebcfebf 100644 --- a/pecan/__init__.py +++ b/pecan/__init__.py @@ -51,6 +51,12 @@ def make_app(root, static_root=None, debug=False, errorcfg={}, # Support for serving static files (for development convenience) if static_root: app = StaticFileMiddleware(app, static_root) + elif static_root: + from warnings import warn + warn( + "`static_root` is only used when `debug` is True, ignoring", + RuntimeWarning + ) # Support for simple Apache-style logs if isinstance(logging, dict) or logging == True: