format quickstart, fix minor example inconsistency

clean up intersphinx mapping
use current year in docs
use setup.cfg to tag dev builds

Author: davidism

docs/conf.py

@@ -11,12 +11,15 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import os
+import sys
+from datetime import datetime
+import pkg_resources
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
+
 sys.path.append(os.path.abspath('_themes'))
 
 # -- General configuration -----------------------------------------------------
@@ -42,24 +45,23 @@
 
 # General information about the project.
 project = u'Flask-SQLAlchemy'
-copyright = u'2010-2014, Armin Ronacher'
+copyright = u'2010 - {}, Armin Ronacher'.format(datetime.utcnow().year)
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
-import pkg_resources
 try:
     release = pkg_resources.get_distribution('Flask-SQLAlchemy').version
 except pkg_resources.DistributionNotFound:
-    print('To build the documentation, The distribution information of')
+    print('To build the documentation, the distribution information of')
     print('Flask-SQLAlchemy has to be available.  Either install the package')
     print('into your development environment or run "setup.py develop"')
     print('to setup the metadata.  A virtualenv is recommended!')
     sys.exit(1)
-del pkg_resources
 
 if 'dev' in release:
-    release = release.split('dev')[0] + 'dev'
+    release = ''.join(release.partition('dev')[:2])
+
 version = '.'.join(release.split('.')[:2])
 
 # The language for content autogenerated by Sphinx. Refer to documentation
@@ -104,7 +106,7 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 html_theme_options = {
-    'index_logo':       'flask-sqlalchemy.png'
+    'index_logo': 'flask-sqlalchemy.png'
 }
 
 # Add any paths that contain custom themes here, relative to this directory.
@@ -141,9 +143,8 @@
 
 # Custom sidebar templates, maps document names to template names.
 html_sidebars = {
-    'index':    ['sidebarintro.html', 'sourcelink.html', 'searchbox.html'],
-    '**':       ['sidebarlogo.html', 'localtoc.html', 'relations.html',
-                 'sourcelink.html', 'searchbox.html']
+    'index': ['sidebarintro.html', 'sourcelink.html', 'searchbox.html'],
+    '**': ['sidebarlogo.html', 'localtoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html']
 }
 
 # Additional templates that should be rendered to pages, maps page names to
@@ -224,9 +225,11 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'http://docs.python.org/': None,
-                       'http://flask.pocoo.org/docs/': None,
-                       'http://www.sqlalchemy.org/docs/': None}
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'flask': ('http://flask.pocoo.org/docs/', None),
+    'sqlalchemy': ('http://docs.sqlalchemy.org/en/latest/', None)
+}
 pygments_style = 'flask_theme_support.FlaskyStyle'
 
 # fall back if theme is not there

docs/quickstart.rst

@@ -18,7 +18,7 @@ then create the :class:`SQLAlchemy` object by passing it the application.
 
 Once created, that object then contains all the functions and helpers
 from both :mod:`sqlalchemy` and :mod:`sqlalchemy.orm`.  Furthermore it
-provides a class called `Model` that is a declarative base which can be
+provides a class called ``Model`` that is a declarative base which can be
 used to declare models::
 
     from flask import Flask
@@ -44,29 +44,29 @@ used to declare models::
 To create the initial database, just import the `db` object from an
 interactive Python shell and run the
 :meth:`SQLAlchemy.create_all` method to create the
-tables and database:
+tables and database::
 
->>> from yourapplication import db
->>> db.create_all()
+    >>> from yourapplication import db
+    >>> db.create_all()
 
-Boom, and there is your database.  Now to create some users:
+Boom, and there is your database.  Now to create some users::
 
->>> from yourapplication import User
->>> admin = User('admin', '[email protected]')
->>> guest = User('guest', '[email protected]')
+    >>> from yourapplication import User
+    >>> admin = User('admin', '[email protected]')
+    >>> guest = User('guest', '[email protected]')
 
-But they are not yet in the database, so let's make sure they are:
+But they are not yet in the database, so let's make sure they are::
 
->>> db.session.add(admin)
->>> db.session.add(guest)
->>> db.session.commit()
+    >>> db.session.add(admin)
+    >>> db.session.add(guest)
+    >>> db.session.commit()
 
-Accessing the data in database is easy as a pie:
+Accessing the data in database is easy as a pie::
 
->>> users = User.query.all()
-[<User u'admin'>, <User u'guest'>]
->>> admin = User.query.filter_by(username='admin').first()
-<User u'admin'>
+    >>> User.query.all()
+    [<User u'admin'>, <User u'guest'>]
+    >>> User.query.filter_by(username='admin').first()
+    <User u'admin'>
 
 Simple Relationships
 --------------------
@@ -75,7 +75,6 @@ SQLAlchemy connects to relational databases and what relational databases
 are really good at are relations.  As such, we shall have an example of an
 application that uses two tables that have a relationship to each other::
 
-
     from datetime import datetime
 
 
@@ -111,24 +110,24 @@ application that uses two tables that have a relationship to each other::
         def __repr__(self):
             return '<Category %r>' % self.name
 
-First let's create some objects:
+First let's create some objects::
 
->>> py = Category('Python')
->>> p = Post('Hello Python!', 'Python is pretty cool', py)
->>> db.session.add(py)
->>> db.session.add(p)
+    >>> py = Category('Python')
+    >>> p = Post('Hello Python!', 'Python is pretty cool', py)
+    >>> db.session.add(py)
+    >>> db.session.add(p)
 
-Now because we declared `posts` as dynamic relationship in the backref
-it shows up as query:
+Now because we declared ``posts`` as dynamic relationship in the backref
+it shows up as query::
 
->>> py.posts
-<sqlalchemy.orm.dynamic.AppenderBaseQuery object at 0x1027d37d0>
+    >>> py.posts
+    <sqlalchemy.orm.dynamic.AppenderBaseQuery object at 0x1027d37d0>
 
 It behaves like a regular query object so we can ask it for all posts that
-are associated with our test “Python” category:
+are associated with our "Python" category::
 
->>> py.posts.all()
-[<Post 'Hello Python!'>]
+    >>> py.posts.all()
+    [<Post 'Hello Python!'>]
 
 
 Road to Enlightenment
@@ -140,15 +139,15 @@ The only things you need to know compared to plain SQLAlchemy are:
 
     -   all the functions and classes from :mod:`sqlalchemy` and
         :mod:`sqlalchemy.orm`
-    -   a preconfigured scoped session called `session`
+    -   a preconfigured scoped session called ``session``
     -   the :attr:`~SQLAlchemy.metadata`
     -   the :attr:`~SQLAlchemy.engine`
     -   a :meth:`SQLAlchemy.create_all` and :meth:`SQLAlchemy.drop_all`
         methods to create and drop tables according to the models.
     -   a :class:`Model` baseclass that is a configured declarative base.
 
 2.  The :class:`Model` declarative base class behaves like a regular
-    Python class but has a `query` attribute attached that can be used to
+    Python class but has a ``query`` attribute attached that can be used to
     query the model.  (:class:`Model` and :class:`BaseQuery`)
 
 3.  You have to commit the session, but you don't have to remove it at

setup.cfg

@@ -1,5 +1,6 @@
 [egg_info]
-tag_date = true
+tag_build = .dev
+tag_date = 1
 
 [aliases]
 release = egg_info -RDb ''

setup.py

@@ -15,10 +15,9 @@
 """
 from setuptools import setup
 
-
 setup(
     name='Flask-SQLAlchemy',
-    version='3.0-dev',
+    version='3.0',
     url='http://github.com/mitsuhiko/flask-sqlalchemy',
     license='BSD',
     author='Armin Ronacher',