Permalink
Browse files

Add changelog and polish docs for relative URLs.

  • Loading branch information...
1 parent b3e9081 commit 964ad0bfbd66f983a355bf7d73b12b426d3e631d @SimonSapin SimonSapin committed Aug 13, 2012
Showing with 38 additions and 11 deletions.
  1. +22 −4 docs/index.rst
  2. +16 −7 flask_frozen/__init__.py
View
@@ -174,7 +174,9 @@ also useful to test your *URL generators* and see that nothing is missing,
before deploying to a production server.
You can open the newly generated static HTML files in a web browser, but
-links probably won’t work. To work around this, use the :meth:`~Freezer.run`
+links probably won’t work. The ``FREEZER_RELATIVE_URLS`` `configuration`_
+can fix this, but adds a visible ``index.html`` to the links.
+Alternatively, use the :meth:`~Freezer.run`
method to start an HTTP server on the build result,
so you can check that everything is fine before uploading::
@@ -185,7 +187,7 @@ so you can check that everything is fine before uploading::
the reloader kicks in. But the reloader only watches Python files, not
templates or static files. Because of that, you probably want to use
:meth:`Freezer.run` only for testing the URL generators. For everything
-else use the usual :meth:`flask.Flask.run`.
+else use the usual :meth:`app.run() <flask.Flask.run>`.
`Flask-Script <http://packages.python.org/Flask-Script/>`_ may come in handy
here.
@@ -233,8 +235,15 @@ are accepted:
.. versionadded:: 0.8
``FREEZER_RELATIVE_URLS``
- If set to ``True``, Frozen-Flask will generate relative urls for each
- call made by the site to :func:`flask.url_for`. Defaults to ``False``.
+ If set to ``True``, Frozen-Flask will patch the Jinja environment so that
+ ``url_for()`` returns relative URLs. Defaults to ``False``.
+ Python code is not affected unless you use :func:`relative_url_for`
+ explicitly. This enable the frozen site to be browsed without a web server
+ (opening the files directly in a browser) but appends a visible
+ ``index.html`` to URLs that would otherwise end with ``/``.
+
+ .. versionadded:: 0.10
+
.. _mime-types:
@@ -313,6 +322,15 @@ API reference
Changelog
---------
+Version 0.10
+~~~~~~~~~~~~
+
+Not released yet.
+
+Add the ``FREEZER_RELATIVE_URLS`` config and the :func:`relative_url_for`
+function.
+
+
Version 0.9
~~~~~~~~~~~
View
@@ -58,7 +58,7 @@ def posix_relpath(path, start):
__all__ = ['Freezer']
-VERSION = '0.10'
+VERSION = '0.10a0'
class MissingURLGeneratorWarning(Warning):
@@ -433,13 +433,22 @@ def patch_url_for(app):
def relative_url_for(endpoint, **values):
"""
- Like :func:`~flask.url_for`, but generates relative paths
- for each request.
+ Like :func:`~flask.url_for`, but returns relative URLs if possible.
+
+ Absolute URLs (with ``_external=True`` or to a different subdomain) are
+ unchanged, but eg. ``/foo/bar`` becomes ``../bar``, depending on the
+ current request context's path. (This, of course, requires a Flask
+ :ref:`request context <flask:request-context>`.)
+
+ URLs that would otherwise end with ``/`` get ``index.html`` appended,
+ as Frozen-Flask does in filenames. Because of this behavior, this function
+ should only with Frozen-Flask, not when running the application in
+ :meth:`app.run() <flask.Flask.run>` or another WSGI sever.
+
+ If the ``FREEZER_RELATIVE_URLS`` `configuration`_ is True, Frozen-Flask
+ will automatically patch the application's Jinja environment so that
+ ``url_for`` in templates is this function.
- .. note::
- This function is not safe for general use in a Flask
- application, only when freezing, since Flask distinguishes
- between routes such as `/` and `/index.html`.
"""
url = url_for(endpoint, **values)

0 comments on commit 964ad0b

Please sign in to comment.