From a8f570cc6225e22d0411cf20b0102a92f319e4e3 Mon Sep 17 00:00:00 2001 From: defuz Date: Wed, 5 Nov 2014 06:45:22 +0300 Subject: [PATCH] docs: :file:`app.py`, :file:`yourapp/templates` --- docs/blueprints.rst | 8 ++++---- docs/cli.rst | 6 +++--- docs/config.rst | 2 +- docs/deploying/mod_wsgi.rst | 2 +- docs/extensiondev.rst | 10 +++++----- docs/extensions.rst | 4 ++-- docs/foreword.rst | 2 +- docs/installation.rst | 2 +- docs/patterns/appfactories.rst | 10 +++++----- docs/patterns/distribute.rst | 20 ++++++++++---------- docs/patterns/fabric.rst | 6 +++--- docs/patterns/flashing.rst | 2 +- docs/patterns/jquery.rst | 4 ++-- docs/patterns/lazyloading.rst | 2 +- docs/patterns/mongokit.rst | 4 ++-- docs/patterns/packages.rst | 16 ++++++++-------- docs/patterns/sqlalchemy.rst | 8 ++++---- docs/patterns/templateinheritance.rst | 2 +- docs/patterns/wtforms.rst | 6 +++--- docs/quickstart.rst | 10 +++++----- docs/testing.rst | 2 +- docs/tutorial/css.rst | 2 +- docs/tutorial/dbinit.rst | 2 +- docs/tutorial/folders.rst | 4 ++-- docs/tutorial/setup.rst | 16 ++++++++-------- docs/tutorial/templates.rst | 4 ++-- docs/tutorial/views.rst | 2 +- docs/upgrading.rst | 12 ++++++------ examples/flaskr/README | 4 ++-- examples/minitwit/README | 4 ++-- flask/app.py | 6 +++--- flask/helpers.py | 2 +- 32 files changed, 93 insertions(+), 93 deletions(-) diff --git a/docs/blueprints.rst b/docs/blueprints.rst index 6569cc51..d22220b2 100644 --- a/docs/blueprints.rst +++ b/docs/blueprints.rst @@ -159,7 +159,7 @@ blueprint:: admin = Blueprint('admin', __name__, static_folder='static') By default the rightmost part of the path is where it is exposed on the -web. Because the folder is called ``static`` here it will be available at +web. Because the folder is called :file:`static` here it will be available at the location of the blueprint + ``/static``. Say the blueprint is registered for ``/admin`` the static folder will be at ``/admin/static``. @@ -185,10 +185,10 @@ provides in the actual application. So if you have a blueprint in the folder ``yourapplication/admin`` and you want to render the template ``'admin/index.html'`` and you have provided ``templates`` as a `template_folder` you will have to create a file like -this: ``yourapplication/admin/templates/admin/index.html``. +this: :file:`yourapplication/admin/templates/admin/index.html`. To further reiterate this: if you have a blueprint named ``admin`` and you -want to render a template called ``index.html`` which is specific to this +want to render a template called :file:`index.html` which is specific to this blueprint, the best idea is to lay out your templates like this:: yourpackage/ @@ -199,7 +199,7 @@ blueprint, the best idea is to lay out your templates like this:: index.html __init__.py -And then when you want to render the template, use ``admin/index.html`` as +And then when you want to render the template, use :file:`admin/index.html` as the name to look up the template by. If you encounter problems loading the correct templates enable the ``EXPLAIN_TEMPLATE_LOADING`` config variable which will instruct Flask to print out the steps it goes through diff --git a/docs/cli.rst b/docs/cli.rst index d6d45a50..4b7c051a 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -35,7 +35,7 @@ automatically and discover the module name but that might not always work. In that imported file the name of the app needs to be called ``app`` or optionally be specified after a colon. -Given a ``hello.py`` file with the application in it named ``app`` this is +Given a :file:`hello.py` file with the application in it named ``app`` this is how it can be run. Environment variables (On Windows use ``set`` instead of ``export``):: @@ -133,7 +133,7 @@ For instance if you have a factory function that creates an application from a filename you could make a separate file that creates such an application from an environment variable. -This could be a file named ``autoapp.py`` with these contents:: +This could be a file named :file:`autoapp.py` with these contents:: import os from yourapplication import create_app @@ -179,7 +179,7 @@ We won't go into detail now about the differences but if you are curious you can have a look at the :ref:`script-info-object` section to learn all about it. -To explain all of this, here is an example ``manage.py`` script that +To explain all of this, here is an example :file:`manage.py` script that manages a hypothetical wiki application. We will go through the details afterwards:: diff --git a/docs/config.rst b/docs/config.rst index c3909d85..45362eaf 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -323,7 +323,7 @@ in the example above:: app.config.from_object('yourapplication.default_settings') app.config.from_envvar('YOURAPPLICATION_SETTINGS') -Then you just have to add a separate `config.py` file and export +Then you just have to add a separate :file:`config.py` file and export ``YOURAPPLICATION_SETTINGS=/path/to/config.py`` and you are done. However there are alternative ways as well. For example you could use imports or subclassing. diff --git a/docs/deploying/mod_wsgi.rst b/docs/deploying/mod_wsgi.rst index e91aedc9..4d5a3fdc 100644 --- a/docs/deploying/mod_wsgi.rst +++ b/docs/deploying/mod_wsgi.rst @@ -132,7 +132,7 @@ If your application does not run, follow this guide to troubleshoot: You have a ``app.run()`` call in your application file that is not guarded by an ``if __name__ == '__main__':`` condition. Either remove that :meth:`~flask.Flask.run` call from the file and move it - into a separate `run.py` file or put it into such an if block. + into a separate :file:`run.py` file or put it into such an if block. **Problem:** application gives permission errors Probably caused by your application running as the wrong user. Make diff --git a/docs/extensiondev.rst b/docs/extensiondev.rst index 4e0e45d8..42d0348a 100644 --- a/docs/extensiondev.rst +++ b/docs/extensiondev.rst @@ -27,7 +27,7 @@ The name of the actual extension (the human readable name) however would be something like "Flask-SimpleXML". Make sure to include the name "Flask" somewhere in that name and that you check the capitalization. This is how users can then register dependencies to your extension in -their `setup.py` files. +their :file:`setup.py` files. Flask sets up a redirect package called :data:`flask.ext` where users should import the extensions from. If you for instance have a package @@ -42,7 +42,7 @@ a requirement because many people will use patterns like the unittests and to support multiple configurations. Because of that it is crucial that your application supports that kind of behavior. -Most importantly the extension must be shipped with a `setup.py` file and +Most importantly the extension must be shipped with a :file:`setup.py` file and registered on PyPI. Also the development checkout link should work so that people can easily install the development version into their virtualenv without having to download the library by hand. @@ -70,7 +70,7 @@ Here's the contents of the most important files: setup.py ```````` -The next file that is absolutely required is the `setup.py` file which is +The next file that is absolutely required is the :file:`setup.py` file which is used to install your Flask extension. The following contents are something you can work with:: @@ -366,7 +366,7 @@ extension to be approved you have to follow these guidelines: or ``python setup.py test``. For test suites invoked with ``make test`` the extension has to ensure that all dependencies for the test are installed automatically. If tests are invoked with ``python setup.py - test``, test dependencies can be specified in the `setup.py` file. The + test``, test dependencies can be specified in the :file:`setup.py` file. The test suite also has to be part of the distribution. 3. APIs of approved extensions will be checked for the following characteristics: @@ -380,7 +380,7 @@ extension to be approved you have to follow these guidelines: 5. The naming scheme for official extensions is *Flask-ExtensionName* or *ExtensionName-Flask*. 6. Approved extensions must define all their dependencies in the - `setup.py` file unless a dependency cannot be met because it is not + :file:`setup.py` file unless a dependency cannot be met because it is not available on PyPI. 7. The extension must have documentation that uses one of the two Flask themes for Sphinx documentation. diff --git a/docs/extensions.rst b/docs/extensions.rst index 4f80f1e6..7a558138 100644 --- a/docs/extensions.rst +++ b/docs/extensions.rst @@ -9,7 +9,7 @@ Finding Extensions Flask extensions are listed on the `Flask Extension Registry`_ and can be downloaded with ``easy_install`` or ``pip``. If you add a Flask extension -as dependency to your ``requirements.rst`` or ``setup.py`` file they are +as dependency to your ``requirements.rst`` or :file:`setup.py` file they are usually installed with a simple command or when your application installs. Using Extensions @@ -32,7 +32,7 @@ depending on how the extension is distributed. If you want to develop an application that supports Flask 0.7 or earlier you should still import from the :data:`flask.ext` package. We provide you with a compatibility module that provides this package for older versions of Flask. You can -download it from github: `flaskext_compat.py`_ +download it from github: :file:`flaskext_compat.py`_ And here is how you can use it:: diff --git a/docs/foreword.rst b/docs/foreword.rst index 167f2f41..7b151f53 100644 --- a/docs/foreword.rst +++ b/docs/foreword.rst @@ -30,7 +30,7 @@ Configuration and Conventions Flask has many configuration values, with sensible defaults, and a few conventions when getting started. By convention templates and static files are stored in subdirectories within the application's Python source tree, with the -names `templates` and `static` respectively. While this can be changed you +names :file:`templates` and :file:`static` respectively. While this can be changed you usually don't have to, especially when getting started. Growing with Flask diff --git a/docs/installation.rst b/docs/installation.rst index bd872163..104706a4 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -150,7 +150,7 @@ If you don't currently have either, then `get-pip.py` will install both for you To install the latest setuptools, you can use its bootstrap file: -`ez_setup.py`_ +:file:`ez_setup.py`_ Either should be double-clickable once you download them. If you already have pip, you can upgrade them by running:: diff --git a/docs/patterns/appfactories.rst b/docs/patterns/appfactories.rst index 2f387f1a..2ed7e4f7 100644 --- a/docs/patterns/appfactories.rst +++ b/docs/patterns/appfactories.rst @@ -60,9 +60,9 @@ Factories & Extensions It's preferable to create your extensions and app factories so that the extension object does not initially get bound to the application. -Using `Flask-SQLAlchemy `_, +Using `Flask-SQLAlchemy `_, as an example, you should not do something along those lines:: - + def create_app(config_filename): app = Flask(__name__) app.config.from_pyfile(config_filename) @@ -72,7 +72,7 @@ as an example, you should not do something along those lines:: But, rather, in model.py (or equivalent):: db = SQLAlchemy() - + and in your application.py (or equivalent):: def create_app(config_filename): @@ -83,7 +83,7 @@ and in your application.py (or equivalent):: db.init_app(app) Using this design pattern, no application-specific state is stored on the -extension object, so one extension object can be used for multiple apps. +extension object, so one extension object can be used for multiple apps. For more information about the design of extensions refer to :doc:`/extensiondev`. Using Applications @@ -91,7 +91,7 @@ Using Applications So to use such an application you then have to create the application first in a separate file otherwise the ``flask`` command won't be able -to find it. Here an example `exampleapp.py` file that creates such +to find it. Here an example :file:`exampleapp.py` file that creates such an application:: from yourapplication import create_app diff --git a/docs/patterns/distribute.rst b/docs/patterns/distribute.rst index 466032dc..402e88d1 100644 --- a/docs/patterns/distribute.rst +++ b/docs/patterns/distribute.rst @@ -27,7 +27,7 @@ Flask itself, and all the libraries you can find on the cheeseshop are distributed with either distribute, the older setuptools or distutils. In this case we assume your application is called -`yourapplication.py` and you are not using a module, but a :ref:`package +:file:`yourapplication.py` and you are not using a module, but a :ref:`package `. Distributing resources with standard modules is not supported by `distribute`_ so we will not bother with it. If you have not yet converted your application into a package, head over to the @@ -42,13 +42,13 @@ Basic Setup Script Because you have Flask running, you either have setuptools or distribute available on your system anyways. If you do not, fear not, there is a -script to install it for you: `distribute_setup.py`_. Just download and +script to install it for you: :file:`distribute_setup.py`_. Just download and run with your Python interpreter. Standard disclaimer applies: :ref:`you better use a virtualenv `. -Your setup code always goes into a file named `setup.py` next to your +Your setup code always goes into a file named :file:`setup.py` next to your application. The name of the file is only convention, but because everybody will look for a file with that name, you better not change it. @@ -56,7 +56,7 @@ Yes, even if you are using `distribute`, you are importing from a package called `setuptools`. `distribute` is fully backwards compatible with `setuptools`, so it also uses the same import name. -A basic `setup.py` file for a Flask application looks like this:: +A basic :file:`setup.py` file for a Flask application looks like this:: from setuptools import setup @@ -83,7 +83,7 @@ the `find_packages` function:: Most parameters to the `setup` function should be self explanatory, `include_package_data` and `zip_safe` might not be. -`include_package_data` tells distribute to look for a `MANIFEST.in` file +`include_package_data` tells distribute to look for a :file:`MANIFEST.in` file and install all the entries that match as package data. We will use this to distribute the static files and templates along with the Python module (see :ref:`distributing-resources`). The `zip_safe` flag can be used to @@ -98,16 +98,16 @@ Distributing Resources ---------------------- If you try to install the package you just created, you will notice that -folders like `static` or `templates` are not installed for you. The +folders like :file:`static` or :file:`templates` are not installed for you. The reason for this is that distribute does not know which files to add for -you. What you should do, is to create a `MANIFEST.in` file next to your -`setup.py` file. This file lists all the files that should be added to +you. What you should do, is to create a :file:`MANIFEST.in` file next to your +:file:`setup.py` file. This file lists all the files that should be added to your tarball:: recursive-include yourapplication/templates * recursive-include yourapplication/static * -Don't forget that even if you enlist them in your `MANIFEST.in` file, they +Don't forget that even if you enlist them in your :file:`MANIFEST.in` file, they won't be installed for you unless you set the `include_package_data` parameter of the `setup` function to ``True``! @@ -145,7 +145,7 @@ Installing / Developing ----------------------- To install your application (ideally into a virtualenv) just run the -`setup.py` script with the `install` parameter. It will install your +:file:`setup.py` script with the `install` parameter. It will install your application into the virtualenv's site-packages folder and also download and install all dependencies:: diff --git a/docs/patterns/fabric.rst b/docs/patterns/fabric.rst index bdbfa634..48915a39 100644 --- a/docs/patterns/fabric.rst +++ b/docs/patterns/fabric.rst @@ -15,7 +15,7 @@ upfront: - Fabric 1.0 has to be installed locally. This tutorial assumes the latest version of Fabric. - The application already has to be a package and requires a working - `setup.py` file (:ref:`distribute-deployment`). + :file:`setup.py` file (:ref:`distribute-deployment`). - In the following example we are using `mod_wsgi` for the remote servers. You can of course use your own favourite server there, but for this example we chose Apache + `mod_wsgi` because it's very easy @@ -25,7 +25,7 @@ upfront: Creating the first Fabfile -------------------------- -A fabfile is what controls what Fabric executes. It is named `fabfile.py` +A fabfile is what controls what Fabric executes. It is named :file:`fabfile.py` and executed by the `fab` command. All the functions defined in that file will show up as `fab` subcommands. They are executed on one or more hosts. These hosts can be defined either in the fabfile or on the command @@ -168,7 +168,7 @@ can pack up the application and deploy it:: Fabric will now connect to all servers and run the commands as written down in the fabfile. First it will execute pack so that we have our tarball ready and then it will execute deploy and upload the source code -to all servers and install it there. Thanks to the `setup.py` file we +to all servers and install it there. Thanks to the :file:`setup.py` file we will automatically pull in the required libraries into our virtual environment. diff --git a/docs/patterns/flashing.rst b/docs/patterns/flashing.rst index 475b49fa..880cde5f 100644 --- a/docs/patterns/flashing.rst +++ b/docs/patterns/flashing.rst @@ -38,7 +38,7 @@ So here is a full example:: return redirect(url_for('index')) return render_template('login.html', error=error) -And here the ``layout.html`` template which does the magic: +And here the :file:`layout.html` template which does the magic: .. sourcecode:: html+jinja diff --git a/docs/patterns/jquery.rst b/docs/patterns/jquery.rst index 3ac1412d..1d3b2149 100644 --- a/docs/patterns/jquery.rst +++ b/docs/patterns/jquery.rst @@ -119,9 +119,9 @@ special error reporting in that case. The HTML -------- -Your index.html template either has to extend a `layout.html` template with +Your index.html template either has to extend a :file:`layout.html` template with jQuery loaded and the `$SCRIPT_ROOT` variable set, or do that on the top. -Here's the HTML code needed for our little application (`index.html`). +Here's the HTML code needed for our little application (:file:`index.html`). Notice that we also drop the script directly into the HTML here. It is usually a better idea to have that in a separate script file: diff --git a/docs/patterns/lazyloading.rst b/docs/patterns/lazyloading.rst index 50ad6fa8..04be53f7 100644 --- a/docs/patterns/lazyloading.rst +++ b/docs/patterns/lazyloading.rst @@ -33,7 +33,7 @@ Imagine the current application looks somewhat like this:: pass Then the centralized approach you would have one file with the views -(`views.py`) but without any decorator:: +(:file:`views.py`) but without any decorator:: def index(): pass diff --git a/docs/patterns/mongokit.rst b/docs/patterns/mongokit.rst index db12fda6..860114bf 100644 --- a/docs/patterns/mongokit.rst +++ b/docs/patterns/mongokit.rst @@ -20,7 +20,7 @@ Declarative The default behavior of MongoKit is the declarative one that is based on common ideas from Django or the SQLAlchemy declarative extension. -Here an example `app.py` module for your application:: +Here an example :file:`app.py` module for your application:: from flask import Flask from mongokit import Connection, Document @@ -47,7 +47,7 @@ MongoDB is schemaless. This means you can modify the data structure from one insert query to the next without any problem. MongoKit is just schemaless too, but implements some validation to ensure data integrity. -Here is an example document (put this also into `app.py`, e.g.):: +Here is an example document (put this also into :file:`app.py`, e.g.):: def max_length(length): def validate(value): diff --git a/docs/patterns/packages.rst b/docs/patterns/packages.rst index 1c7f9bd0..e7248b6f 100644 --- a/docs/patterns/packages.rst +++ b/docs/patterns/packages.rst @@ -22,7 +22,7 @@ Simple Packages To convert that into a larger one, just create a new folder `yourapplication` inside the existing one and move everything below it. -Then rename `yourapplication.py` to `__init__.py`. (Make sure to delete +Then rename :file:`yourapplication.py` to :file:`__init__.py`. (Make sure to delete all `.pyc` files first, otherwise things would most likely break) You should then end up with something like that:: @@ -41,7 +41,7 @@ You should then end up with something like that:: But how do you run your application now? The naive ``python yourapplication/__init__.py`` will not work. Let's just say that Python does not want modules in packages to be the startup file. But that is not -a big problem, just add a new file called `runserver.py` next to the inner +a big problem, just add a new file called :file:`runserver.py` next to the inner `yourapplication` folder with the following contents:: from yourapplication import app @@ -52,21 +52,21 @@ into multiple modules. The only thing you have to remember is the following quick checklist: 1. the `Flask` application object creation has to be in the - `__init__.py` file. That way each module can import it safely and the + :file:`__init__.py` file. That way each module can import it safely and the `__name__` variable will resolve to the correct package. 2. all the view functions (the ones with a :meth:`~flask.Flask.route` - decorator on top) have to be imported in the `__init__.py` file. + decorator on top) have to be imported in the :file:`__init__.py` file. Not the object itself, but the module it is in. Import the view module **after the application object is created**. -Here's an example `__init__.py`:: +Here's an example :file:`__init__.py`:: from flask import Flask app = Flask(__name__) import yourapplication.views -And this is what `views.py` would look like:: +And this is what :file:`views.py` would look like:: from yourapplication import app @@ -93,9 +93,9 @@ You should then end up with something like that:: Every Python programmer hates them, and yet we just added some: circular imports (That's when two modules depend on each other. In this - case `views.py` depends on `__init__.py`). Be advised that this is a + case :file:`views.py` depends on :file:`__init__.py`). Be advised that this is a bad idea in general but here it is actually fine. The reason for this is - that we are not actually using the views in `__init__.py` and just + that we are not actually using the views in :file:`__init__.py` and just ensuring the module is imported and we are doing that at the bottom of the file. diff --git a/docs/patterns/sqlalchemy.rst b/docs/patterns/sqlalchemy.rst index d34f39be..7419583b 100644 --- a/docs/patterns/sqlalchemy.rst +++ b/docs/patterns/sqlalchemy.rst @@ -33,7 +33,7 @@ SQLAlchemy. It allows you to define tables and models in one go, similar to how Django works. In addition to the following text I recommend the official documentation on the `declarative`_ extension. -Here the example `database.py` module for your application:: +Here the example :file:`database.py` module for your application:: from sqlalchemy import create_engine from sqlalchemy.orm import scoped_session, sessionmaker @@ -70,7 +70,7 @@ when the application shuts down:: def shutdown_session(exception=None): db_session.remove() -Here is an example model (put this into `models.py`, e.g.):: +Here is an example model (put this into :file:`models.py`, e.g.):: from sqlalchemy import Column, Integer, String from yourapplication.database import Base @@ -122,7 +122,7 @@ flexible but a little more to type. In general it works like the declarative approach, so make sure to also split up your application into multiple modules in a package. -Here is an example `database.py` module for your application:: +Here is an example :file:`database.py` module for your application:: from sqlalchemy import create_engine, MetaData from sqlalchemy.orm import scoped_session, sessionmaker @@ -145,7 +145,7 @@ application module:: def shutdown_session(exception=None): db_session.remove() -Here is an example table and model (put this into `models.py`):: +Here is an example table and model (put this into :file:`models.py`):: from sqlalchemy import Table, Column, Integer, String from sqlalchemy.orm import mapper diff --git a/docs/patterns/templateinheritance.rst b/docs/patterns/templateinheritance.rst index 1292f26e..dbcb4163 100644 --- a/docs/patterns/templateinheritance.rst +++ b/docs/patterns/templateinheritance.rst @@ -14,7 +14,7 @@ with an example. Base Template ------------- -This template, which we'll call ``layout.html``, defines a simple HTML skeleton +This template, which we'll call :file:`layout.html`, defines a simple HTML skeleton document that you might use for a simple two-column page. It's the job of "child" templates to fill the empty blocks with content: diff --git a/docs/patterns/wtforms.rst b/docs/patterns/wtforms.rst index 0e41d594..c42d94ee 100644 --- a/docs/patterns/wtforms.rst +++ b/docs/patterns/wtforms.rst @@ -77,7 +77,7 @@ how easy this is. WTForms does half the form generation for us already. To make it even nicer, we can write a macro that renders a field with label and a list of errors if there are any. -Here's an example `_formhelpers.html` template with such a macro: +Here's an example :file:`_formhelpers.html` template with such a macro: .. sourcecode:: html+jinja @@ -102,8 +102,8 @@ the input element. Note that WTForms returns standard Python unicode strings, so we have to tell Jinja2 that this data is already HTML escaped with the `|safe` filter. -Here the `register.html` template for the function we used above which -takes advantage of the `_formhelpers.html` template: +Here the :file:`register.html` template for the function we used above which +takes advantage of the :file:`_formhelpers.html` template: .. sourcecode:: html+jinja diff --git a/docs/quickstart.rst b/docs/quickstart.rst index d032b3c6..8acb0e97 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -20,8 +20,8 @@ A minimal Flask application looks something like this:: def hello_world(): return 'Hello World!' -Just save it as `hello.py` (or something similar) and run it with your Python -interpreter. Make sure to not call your application `flask.py` because this +Just save it as :file:`hello.py` (or something similar) and run it with your Python +interpreter. Make sure to not call your application :file:`flask.py` because this would conflict with Flask itself. To run the application you can either use the ``flask`` command or @@ -370,14 +370,14 @@ Static Files Dynamic web applications also need static files. That's usually where the CSS and JavaScript files are coming from. Ideally your web server is configured to serve them for you, but during development Flask can do that -as well. Just create a folder called `static` in your package or next to +as well. Just create a folder called :file:`static` in your package or next to your module and it will be available at `/static` on the application. To generate URLs for static files, use the special ``'static'`` endpoint name:: url_for('static', filename='style.css') -The file has to be stored on the filesystem as ``static/style.css``. +The file has to be stored on the filesystem as :file:`static/style.css`. Rendering Templates ------------------- @@ -399,7 +399,7 @@ Here's a simple example of how to render a template:: def hello(name=None): return render_template('hello.html', name=name) -Flask will look for templates in the `templates` folder. So if your +Flask will look for templates in the :file:`templates` folder. So if your application is a module, this folder is next to that module, if it's a package it's actually inside your package: diff --git a/docs/testing.rst b/docs/testing.rst index 650a2758..eaf8a783 100644 --- a/docs/testing.rst +++ b/docs/testing.rst @@ -30,7 +30,7 @@ The Testing Skeleton -------------------- In order to test the application, we add a second module -(`flaskr_tests.py`) and create a unittest skeleton there:: +(:file:`flaskr_tests.py`) and create a unittest skeleton there:: import os import flaskr diff --git a/docs/tutorial/css.rst b/docs/tutorial/css.rst index b86225c4..01d15699 100644 --- a/docs/tutorial/css.rst +++ b/docs/tutorial/css.rst @@ -4,7 +4,7 @@ Step 7: Adding Style ==================== Now that everything else works, it's time to add some style to the -application. Just create a stylesheet called `style.css` in the `static` +application. Just create a stylesheet called :file:`style.css` in the :file:`static` folder we created before: .. sourcecode:: css diff --git a/docs/tutorial/dbinit.rst b/docs/tutorial/dbinit.rst index e3dc60fb..43febd74 100644 --- a/docs/tutorial/dbinit.rst +++ b/docs/tutorial/dbinit.rst @@ -22,7 +22,7 @@ for you to the application. To do this we can create a function and hook it into the ``flask`` command that initializes the database. Let me show you the code first. Just add -this function below the `connect_db` function in `flaskr.py`:: +this function below the `connect_db` function in :file:`flaskr.py`:: def init_db(): db = get_db() diff --git a/docs/tutorial/folders.rst b/docs/tutorial/folders.rst index 550d5a9b..4723f797 100644 --- a/docs/tutorial/folders.rst +++ b/docs/tutorial/folders.rst @@ -13,9 +13,9 @@ application:: The `flaskr` folder is not a python package, but just something where we drop our files. We will then put our database schema as well as main module into this folder. It is done in the following way. The files inside -the `static` folder are available to users of the application via HTTP. +the :file:`static` folder are available to users of the application via HTTP. This is the place where css and javascript files go. Inside the -`templates` folder Flask will look for `Jinja2`_ templates. The +:file:`templates` folder Flask will look for `Jinja2`_ templates. The templates you create later in the tutorial will go in this directory. Continue with :ref:`tutorial-schema`. diff --git a/docs/tutorial/setup.rst b/docs/tutorial/setup.rst index 1fe4ea59..6180a5e2 100644 --- a/docs/tutorial/setup.rst +++ b/docs/tutorial/setup.rst @@ -11,7 +11,7 @@ directly into the module, and this is what we will be doing here. However a cleaner solution would be to create a separate `.ini` or `.py` file and load that or import the values from there. -First we add the imports in `flaskr.py`:: +First we add the imports in :file:`flaskr.py`:: # all the imports import os @@ -20,7 +20,7 @@ First we add the imports in `flaskr.py`:: render_template, flash Next we can create our actual application and initialize it with the -config from the same file, in `flaskr.py`:: +config from the same file, in :file:`flaskr.py`:: # create our little application :) app = Flask(__name__) @@ -54,14 +54,14 @@ can update it with new values. :ref:`instance-folders` instead. Usually, it is a good idea to load a separate, environment specific -configuration file. Flask allows you to import multiple configurations and it -will use the setting defined in the last import. This enables robust -configuration setups. :meth:`~flask.Config.from_envvar` can help achieve this. - +configuration file. Flask allows you to import multiple configurations and it +will use the setting defined in the last import. This enables robust +configuration setups. :meth:`~flask.Config.from_envvar` can help achieve this. + app.config.from_envvar('FLASKR_SETTINGS', silent=True) -Simply define the environment variable :envvar:`FLASKR_SETTINGS` that points to -a config file to be loaded. The silent switch just tells Flask to not complain +Simply define the environment variable :envvar:`FLASKR_SETTINGS` that points to +a config file to be loaded. The silent switch just tells Flask to not complain if no such environment key is set. In addition to that you can use the :meth:`~flask.Config.from_object` diff --git a/docs/tutorial/templates.rst b/docs/tutorial/templates.rst index 63c0a386..8da16eaf 100644 --- a/docs/tutorial/templates.rst +++ b/docs/tutorial/templates.rst @@ -14,7 +14,7 @@ escaped with their XML equivalents. We are also using template inheritance which makes it possible to reuse the layout of the website in all pages. -Put the following templates into the `templates` folder: +Put the following templates into the :file:`templates` folder: .. _Jinja2: http://jinja.pocoo.org/docs/templates @@ -55,7 +55,7 @@ the session: show_entries.html ----------------- -This template extends the `layout.html` template from above to display the +This template extends the :file:`layout.html` template from above to display the messages. Note that the `for` loop iterates over the messages we passed in with the :func:`~flask.render_template` function. We also tell the form to submit to your `add_entry` function and use ``POST`` as HTTP diff --git a/docs/tutorial/views.rst b/docs/tutorial/views.rst index 8d34bce4..1801bb66 100644 --- a/docs/tutorial/views.rst +++ b/docs/tutorial/views.rst @@ -16,7 +16,7 @@ returned from the cursor look a bit like tuples because we are using the :class:`sqlite3.Row` row factory. The view function will pass the entries as dicts to the -`show_entries.html` template and return the rendered one:: +:file:`show_entries.html` template and return the rendered one:: @app.route('/') def show_entries(): diff --git a/docs/upgrading.rst b/docs/upgrading.rst index 019019d0..0a83dd9f 100644 --- a/docs/upgrading.rst +++ b/docs/upgrading.rst @@ -136,11 +136,11 @@ To apply the upgrade script do the following: patch -p1 < patchfile.diff 5. If you were using per-module template folders you need to move some - templates around. Previously if you had a folder named ``templates`` + templates around. Previously if you had a folder named :file:`templates` next to a blueprint named ``admin`` the implicit template path - automatically was ``admin/index.html`` for a template file called - ``templates/index.html``. This no longer is the case. Now you need - to name the template ``templates/admin/index.html``. The tool will + automatically was :file:`admin/index.html` for a template file called + :file:`templates/index.html`. This no longer is the case. Now you need + to name the template :file:`templates/admin/index.html`. The tool will not detect this so you will have to do that on your own. Please note that deprecation warnings are disabled by default starting @@ -271,7 +271,7 @@ to upgrade. What changed? modules. - Blueprints do not automatically provide static folders. They will also no longer automatically export templates from a folder called - `templates` next to their location however but it can be enabled from + :file:`templates` next to their location however but it can be enabled from the constructor. Same with static files: if you want to continue serving static files you need to tell the constructor explicitly the path to the static folder (which can be relative to the blueprint's @@ -279,7 +279,7 @@ to upgrade. What changed? - Rendering templates was simplified. Now the blueprints can provide template folders which are added to a general template searchpath. This means that you need to add another subfolder with the blueprint's - name into that folder if you want ``blueprintname/template.html`` as + name into that folder if you want :file:`blueprintname/template.html` as the template name. If you continue to use the `Module` object which is deprecated, Flask will diff --git a/examples/flaskr/README b/examples/flaskr/README index d7cb28f7..f149b4db 100644 --- a/examples/flaskr/README +++ b/examples/flaskr/README @@ -23,8 +23,8 @@ the application will greet you on http://localhost:5000/ - + ~ Is it tested? - You betcha. Run the `test_flaskr.py` file to see + You betcha. Run the :file:`test_flaskr.py` file to see the tests pass. diff --git a/examples/minitwit/README b/examples/minitwit/README index 9d84f627..495e8373 100644 --- a/examples/minitwit/README +++ b/examples/minitwit/README @@ -24,8 +24,8 @@ the application will greet you on http://localhost:5000/ - + ~ Is it tested? - You betcha. Run the `test_minitwit.py` file to + You betcha. Run the :file:`test_minitwit.py` file to see the tests pass. diff --git a/flask/app.py b/flask/app.py index 19d84c6a..f6ca4e83 100644 --- a/flask/app.py +++ b/flask/app.py @@ -71,12 +71,12 @@ class Flask(_PackageBoundObject): The name of the package is used to resolve resources from inside the package or the folder the module is contained in depending on if the package parameter resolves to an actual python package (a folder with - an `__init__.py` file inside) or a standard module (just a `.py` file). + an :file:`__init__.py` file inside) or a standard module (just a `.py` file). For more information about resource loading, see :func:`open_resource`. Usually you create a :class:`Flask` instance in your main module or - in the `__init__.py` file of your package like this:: + in the :file:`__init__.py` file of your package like this:: from flask import Flask app = Flask(__name__) @@ -93,7 +93,7 @@ class Flask(_PackageBoundObject): using a package, it's usually recommended to hardcode the name of your package there. - For example if your application is defined in `yourapplication/app.py` + For example if your application is defined in :file:`yourapplication/app.py` you should create it with one of the two versions below:: app = Flask('yourapplication') diff --git a/flask/helpers.py b/flask/helpers.py index 828e8f67..3daccf6d 100644 --- a/flask/helpers.py +++ b/flask/helpers.py @@ -323,7 +323,7 @@ def url_for(endpoint, **values): def get_template_attribute(template_name, attribute): """Loads a macro (or variable) a template exports. This can be used to invoke a macro from within Python code. If you for example have a - template named `_cider.html` with the following contents: + template named :file:`_cider.html` with the following contents: .. sourcecode:: html+jinja