use url_for for url building for static files

docs/sanic/blueprints.md

@@ -93,7 +93,14 @@ def ignore_404s(request, exception):
 Static files can be served globally, under the blueprint prefix.
 
 ```python
-bp.static('/folder/to/serve', '/web/path')
+
+# suppose bp.name == 'bp'
+
+bp.static('/web/path', '/folder/to/serve')
+# also you can pass name parameter to it for url_for
+bp.static('/web/path', '/folder/to/server', name='uploads')
+app.url_for('static', name='bp.uploads', filename='file.txt') == '/bp/web/path/file.txt'
+
 ```
 
 ## Start and stop

docs/sanic/routing.md

@@ -301,3 +301,34 @@ def handler(request):
 # app.url_for('handler') == '/get'
 # app.url_for('post_handler') == '/post'
 ```
+
+## Build URL for static files
+
+You can use `url_for` for static file url building now.
+If it's for file directly, `filename` can be ignored.
+
+```python
+
+app = Sanic('test_static')
+app.static('/static', './static')
+app.static('/uploads', './uploads', name='uploads')
+app.static('/the_best.png', '/home/ubuntu/test.png', name='best_png')
+
+bp = Blueprint('bp', url_prefix='bp')
+bp.static('/static', './static')
+bp.static('/uploads', './uploads', name='uploads')
+bp.static('/the_best.png', '/home/ubuntu/test.png', name='best_png')
+app.blueprint(bp)
+
+# then build the url
+app.url_for('static', filename='file.txt') == '/static/file.txt'
+app.url_for('static', name='static', filename='file.txt') == '/static/file.txt'
+app.url_for('static', name='uploads', filename='file.txt') == 'uploads/file.txt'
+app.url_for('static', name='best_png') == '/the_best.png'
+
+# blueprint url building
+app.url_for('static', name='bp.static', filename='file.txt') == '/bp/static/file.txt'
+app.url_for('static', name='bp.uploads', filename='file.txt') == '/bp/uploads/file.txt'
+app.url_for('static', name='bp.best_png') == '/bp/static/the_best.png'
+
+```

docs/sanic/static_files.md

@@ -6,16 +6,40 @@ filename. The file specified will then be accessible via the given endpoint.
 
 ```python
 from sanic import Sanic
+from sanic.blueprints import Blueprint
+
 app = Sanic(__name__)
 
 # Serves files from the static folder to the URL /static
 app.static('/static', './static')
+# use url_for to build the url, name defaults to 'static' and can be ignored
+app.url_for('static', filename='file.txt') == '/static/file.txt'
+app.url_for('static', name='static', filename='file.txt') == '/static/file.txt'
 
 # Serves the file /home/ubuntu/test.png when the URL /the_best.png
 # is requested
-app.static('/the_best.png', '/home/ubuntu/test.png')
+app.static('/the_best.png', '/home/ubuntu/test.png', name='best_png')
+
+# you can use url_for to build the static file url
+# you can ignore name and filename parameters if you don't define it
+app.url_for('static', name='best_png') == '/the_best.png'
+app.url_for('static', name='best_png', filename='any') == '/the_best.png'
+
+# you need define the name for other static files
+app.static('/another.png', '/home/ubuntu/another.png', name='another')
+app.url_for('static', name='another') == '/another.png'
+app.url_for('static', name='another', filename='any') == '/another.png'
+
+# also, you can use static for blueprint
+bp = Blueprint('bp', url_prefix='/bp')
+bp.static('/static', './static')
+
+# servers the file directly
+bp.static('/the_best.png', '/home/ubuntu/test.png', name='best_png')
+app.blueprint(bp)
+
+app.url_for('static', name='bp.static', filename='file.txt') == '/bp/static/file.txt'
+app.url_for('static', name='bp.best_png') == '/bp/test_best.png'
 
 app.run(host="0.0.0.0", port=8000)
 ```
-
-Note: currently you cannot build a URL for a static file using `url_for`.