Merge pull request #39 from singingwolfboy/update-docs

Update docs

CHANGELOG.rst

@@ -1,6 +1,11 @@
 Changelog
 =========
 
+Unreleased
+**********
+
+* Updated documentation to reference `HyperlinkRelated` instead of `HyperlinkModelSchema`.
+
 0.6.2 (2015-09-16)
 ******************
 

LICENSE

@@ -1,4 +1,4 @@
-Copyright 2014-2015 Steven Loria and contributors
+Copyright 2014-2016 Steven Loria and contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.rst

@@ -90,21 +90,21 @@ Output the data in your views.
     # }
 
 
-http://flask-marshmallow.readthedocs.org/
-=========================================
+http://flask-marshmallow.readthedocs.io/
+========================================
 
 Learn More
 ==========
 
-To learn more about marshmallow, check out its `docs <http://marshmallow.readthedocs.org/en/latest/>`_.
+To learn more about marshmallow, check out its `docs <http://marshmallow.readthedocs.io/en/latest/>`_.
 
 
 
 Project Links
 =============
 
 - Docs: http://flask-marshmallow.rtfd.org/
-- Changelog: http://flask-marshmallow.readthedocs.org/en/latest/changelog.html
+- Changelog: http://flask-marshmallow.readthedocs.io/en/latest/changelog.html
 - PyPI: https://pypi.python.org/pypi/flask-marshmallow
 - Issues: https://github.com/marshmallow-code/flask-marshmallow/issues
 
@@ -115,5 +115,5 @@ MIT licensed. See the bundled `LICENSE <https://github.com/marshmallow-code/flas
 
 
 .. _Flask: http://flask.pocoo.org
-.. _marshmallow: http://marshmallow.readthedocs.org
+.. _marshmallow: http://marshmallow.readthedocs.io
 

docs/conf.py

@@ -12,11 +12,11 @@
 ]
 
 intersphinx_mapping = {
-    'python': ('http://python.readthedocs.org/en/latest/', None),
+    'python': ('http://python.readthedocs.io/en/latest/', None),
     'flask': ('http://flask.pocoo.org/docs/latest/', None),
     'flask-sqlalchemy': ('http://flask-sqlalchemy.pocoo.org/latest/', None),
-    'marshmallow': ('http://marshmallow.readthedocs.org/en/latest/', None),
-    'marshmallow-sqlalchemy': ('http://marshmallow-sqlalchemy.readthedocs.org/en/latest/', None),
+    'marshmallow': ('http://marshmallow.readthedocs.io/en/latest/', None),
+    'marshmallow-sqlalchemy': ('http://marshmallow-sqlalchemy.readthedocs.io/en/latest/', None),
 }
 
 primary_domain = 'py'
@@ -34,7 +34,7 @@
 
 # General information about the project.
 project = u'Flask-Marshmallow'
-copyright = u'2014-2015'
+copyright = u'2014-2016'
 
 version = release = flask_marshmallow.__version__
 exclude_patterns = ['_build']

docs/index.rst

@@ -91,13 +91,13 @@ Output the data in your views.
 Optional Flask-SQLAlchemy Integration
 -------------------------------------
 
-Flask-Marshmallow includes useful extras for integrating with `Flask-SQLAlchemy <http://flask-sqlalchemy.pocoo.org/>`_ and `marshmallow-sqlalchemy <https://marshmallow-sqlalchemy.readthedocs.org>`_.
+Flask-Marshmallow includes useful extras for integrating with `Flask-SQLAlchemy <http://flask-sqlalchemy.pocoo.org/>`_ and `marshmallow-sqlalchemy <https://marshmallow-sqlalchemy.readthedocs.io>`_.
 
 To enable SQLAlchemy integration, make sure that both Flask-SQLAlchemy and marshmallow-sqlalchemy are installed.  ::
 
     pip install -U flask-sqlalchemy marshmallow-sqlalchemy
 
-Next, initialize the `SQLAlchemy <flask.ext.sqlalchemy.SQLAlchemy>` and `Marshmallow <flask_marshmallow.Marshmallow>` extensions, in that order.
+Next, initialize the `~flask_sqlalchemy.SQLAlchemy` and `~flask_marshmallow.Marshmallow` extensions, in that order.
 
 .. code-block:: python
 
@@ -126,23 +126,14 @@ Declare your models like normal.
         id = db.Column(db.Integer, primary_key=True)
         name = db.Column(db.String(255))
 
-        # Used by HyperlinkModelSchema
-        @property
-        def url(self):
-            return url_for('author', id=self.id)
-
     class Book(db.Model):
         id = db.Column(db.Integer, primary_key=True)
         title = db.Column(db.String(255))
         author_id = db.Column(db.Integer, db.ForeignKey('author.id'))
         author = db.relationship('Author', backref='books')
 
-        @property
-        def url(self):
-            return url_for('book', id=self.id)
-
 
-Generate marshmallow `Schemas <marshmallow.Schema>` from your models using `ModelSchema <flask_marshmallow.sqla.ModelSchema>`.
+Generate marshmallow `Schemas <marshmallow.Schema>` from your models using `~flask_marshmallow.sqla.ModelSchema`.
 
 .. code-block:: python
 
@@ -171,25 +162,40 @@ You can now use your schema to dump and load your ORM objects.
     {'id': 1, 'name': 'Chuck Paluhniuk', 'books': [1]}
 
 
-`ModelSchema <flask_marshmallow.sqla.ModelSchema>` is nearly identical in API to `marshmallow_sqlalchemy.ModelSchema` with the following exceptions:
+`~flask_marshmallow.sqla.ModelSchema` is nearly identical in API to `marshmallow_sqlalchemy.ModelSchema` with the following exceptions:
 
-- By default, `ModelSchema <flask_marshmallow.sqla.ModelSchema>` uses the scoped session created by Flask-SQLAlchemy.
-- `ModelSchema <flask_marshmallow.sqla.ModelSchema>` subclasses `flask_marshmallow.Schema`, so it includes the `jsonify <flask_marshmallow.Schema.jsonify>` method. 
-Note: By default, Flask's `jsonify` method sorts the list of keys and returns consistent results to ensure that external HTTP caches aren't trashed. As a side effect, this will override ``ordered=True`<https://marshmallow.readthedocs.org/en/latest/quickstart.html#ordering-output>`_ in the ModelSchema's `class Meta` (if you set it). To disable this, set `JSON_SORT_KEYS=False` in your Flask app config. In production it's recommended to let `jsonify` sort the keys and not set `ordered=True` in your `ModelSchema <flask_marshmallow.sqla.ModelSchema>` in order to minimize generation time and maximize cachability of the results.
+- By default, `~flask_marshmallow.sqla.ModelSchema` uses the scoped session created by Flask-SQLAlchemy.
+- `~flask_marshmallow.sqla.ModelSchema` subclasses `flask_marshmallow.Schema`, so it includes the `~flask_marshmallow.Schema.jsonify` method.
+Note: By default, Flask's `jsonify` method sorts the list of keys and returns consistent results to ensure that external HTTP caches aren't trashed. As a side effect, this will override ``ordered=True`<https://marshmallow.readthedocs.io/en/latest/quickstart.html#ordering-output>`_ in the ModelSchema's `class Meta` (if you set it). To disable this, set `JSON_SORT_KEYS=False` in your Flask app config. In production it's recommended to let `jsonify` sort the keys and not set `ordered=True` in your `~flask_marshmallow.sqla.ModelSchema` in order to minimize generation time and maximize cachability of the results.
 
-You can also use `ma.HyperlinkModelSchema <flask_marshmallow.sqla.HyperlinkModelSchema>` if you want relationships to be represented by hyperlinks rather than primary keys. Models MUST have a ``url`` attribute or property.
+You can also use `ma.HyperlinkRelated <flask_marshmallow.sqla.HyperlinkRelated>` fields if you want relationships to be represented by hyperlinks rather than primary keys.
 
 
 .. code-block:: python
 
-    class AuthorSchema(ma.HyperlinkModelSchema):
-        class Meta:
-            model = Author
-
-    class BookSchema(ma.HyperlinkModelSchema):
+    class BookSchema(ma.ModelSchema):
         class Meta:
             model = Book
+        author = ma.HyperlinkRelated('author_detail')
+
+.. code-block:: python
+
+    >>> with app.test_request_context():
+    ...     print(book_schema.dump(book).data)
+    {'id': 1, 'title': 'Fight Club', 'author': '/authors/1'}
 
+The first argument to the `~flask_marshmallow.sqla.HyperlinkRelated` constructor is the name of the view used to generate the URL, just as you would pass it to the `~flask.url_for` function. If your models and views use the ``id`` attribute
+as a primary key, you're done; otherwise, you must specify the name of the
+attribute used as the primary key.
+
+To represent a one-to-many relationship, wrap the `~flask_marshmallow.sqla.HyperlinkRelated` instance in a `marshmallow.fields.List` field, like this:
+
+.. code-block:: python
+
+    class AuthorSchema(ma.ModelSchema):
+        class Meta:
+            model = Author
+        books = ma.List(ma.HyperlinkRelated('book_detail'))
 
 .. code-block:: python
 
@@ -198,10 +204,6 @@ You can also use `ma.HyperlinkModelSchema <flask_marshmallow.sqla.HyperlinkModel
     {'id': 1, 'name': 'Chuck Paluhniuk', 'books': ['/books/1']}
 
 
-.. note::
-
-    By default, `HyperlinkModelSchema <flask_marshmallow.sqla.HyperlinkModelSchema>` serializes to URLs based on an object's ``url`` attribute. You can override this attribute name by setting the ``MARSHMALLOW_LINK_ATTRIBUTE`` config option of your Flask app.
-
 API
 ===
 
@@ -221,7 +223,7 @@ Useful Links
 - `Flask docs`_
 - `marshmallow docs`_
 
-.. _marshmallow docs: http://marshmallow.readthedocs.org
+.. _marshmallow docs: http://marshmallow.readthedocs.io
 
 .. _Flask docs: http://flask.pocoo.org/docs/
 
@@ -235,6 +237,6 @@ Project Info
    changelog
 
 
-.. _marshmallow: http://marshmallow.readthedocs.org
+.. _marshmallow: http://marshmallow.readthedocs.io
 
  .. _Flask: http://flask.pocoo.org

flask_marshmallow/__init__.py

@@ -6,7 +6,7 @@
     Integrates the marshmallow serialization/deserialization library
     with your Flask application.
 
-    :copyright: (c) 2014-2015 by Steven Loria
+    :copyright: (c) 2014-2016 by Steven Loria
     :license: MIT, see LICENSE for more details.
 """
 import warnings
@@ -95,8 +95,8 @@ class Meta:
             db = SQLAlchemy(app)
             ma = Marshmallow(app)
 
-    This gives you access to `ma.ModelSchema` and `ma.HyperlinkModelSchema`,
-    which generate a marshmallow `Schema <marshmallow.Schema>` based on the passed in model. ::
+    This gives you access to `ma.ModelSchema`, which generates a marshmallow
+    `~marshmallow.Schema` based on the passed in model. ::
 
         class AuthorSchema(ma.ModelSchema):
             class Meta:

flask_marshmallow/fields.py

@@ -142,7 +142,7 @@ def _url_val(val, key, obj, **kwargs):
 
 class Hyperlinks(fields.Field):
     """Field that outputs a dictionary of hyperlinks,
-    given a dictionary schema with :class:`URLFor <flask_marshmallow.fields.URLFor>`
+    given a dictionary schema with :class:`~flask_marshmallow.fields.URLFor`
     objects as values.
 
     Example: ::
@@ -163,7 +163,7 @@ class Hyperlinks(fields.Field):
         })
 
     :param dict schema: A dict that maps names to
-        :class:`URLFor <flask_marshmallow.fields.URLFor>` fields.
+        :class:`~flask_marshmallow.fields.URLFor` fields.
     """
     _CHECK_ATTRIBUTE = False
 

flask_marshmallow/sqla.py

@@ -19,7 +19,7 @@ class DummySession(object):
     pass
 
 class SchemaOpts(msqla.ModelSchemaOpts):
-    """Schema options for `ModelSchema <flask_marshmallow.sqla.ModelSchema>`.
+    """Schema options for `~flask_marshmallow.sqla.ModelSchema`.
     Same as `marshmallow_sqlalchemy.SchemaOpts`, except that we add a
     placeholder `DummySession` if ``sqla_session`` is not defined on
     class Meta. The actual session from `flask_sqlalchemy` gets bound
@@ -44,7 +44,15 @@ class ModelSchema(msqla.ModelSchema, Schema):
     OPTIONS_CLASS = SchemaOpts
 
 class HyperlinkRelated(msqla.fields.Related):
+    """Field that generates hyperlinks to indicate references between models,
+    rather than primary keys.
 
+    :param str endpoint: Flask endpoint name for generated hyperlink.
+    :param str url_key: The attribute containing the reference's primary
+        key. Defaults to "id".
+    :param bool external: Set to `True` if absolute URLs should be used,
+        instead of relative URLs.
+    """
     def __init__(self, endpoint, url_key='id', external=False, **kwargs):
         super(HyperlinkRelated, self).__init__(**kwargs)
         self.endpoint = endpoint