Merge pull request #570 from jfinkels/fix-doc-warnings

Eliminates doc build warnings for bad references.

CHANGES

@@ -17,6 +17,7 @@ Version 1.0.0b2-dev
 
 Not yet released.
 
+- Eliminates all documentation build warnings for bad references.
 - Changes serialization/deserialization to class-based implementation instead
   of a function-based implementation. This also adds support for serialization
   of heterogeneous collections.
@@ -51,21 +52,22 @@ Released on April 2, 2016.
 - :issue:`331,415`: documents the importance of URL encoding when using the ``like``
   operator to filter results.
 - :issue:`376`: add a ``not_like`` operator for filter objects.
-- :issue:`431`: adds a ``url_prefix`` keyword argument to the :class:`APIManager`
-  constructor, so one can specify a URL prefix once for all created APIs.
+- :issue:`431`: adds a ``url_prefix`` keyword argument to the
+  :class:`.APIManager` constructor, so one can specify a URL prefix once for
+  all created APIs.
 - :issue:`449`: roll back the session on any SQLAlchemy error, not just a few.
 - :issue:`432,462`: alias relation names when sorting by multiple attributes on a
   relationship.
 - :issue:`436,453`: use ``__table__.name`` instead of ``__tablename__`` to infer the
   collection name for the SQLAlchemy model.
-- :issue:`440,475`: uses the serialization function provided at the time of invoking
-  :meth:`APIManager.create_api` to serialize each resource correctly, depending
-  on its type.
+- :issue:`440,475`: uses the serialization function provided at the time of
+  invoking :meth:`.APIManager.create_api` to serialize each resource correctly,
+  depending on its type.
 - :issue:`474`: include license files in built wheel for distribution.
 - :issue:`501`: allows empty string for `url_prefix` keyword argument to
-  :meth:`APIManager.create_api`.
+  :meth:`.APIManager.create_api`.
 - :issue:`476`: use the primary key provided at the time of invoking
-  :meth:`APIManager.create_api` to build resource urls in responses.
+  :meth:`.APIManager.create_api` to build resource urls in responses.
 
 Older versions
 --------------
@@ -89,7 +91,7 @@ Released on February 17, 2015.
 - :issue:`167`: allows custom serialization/deserialization functions.
 - :issue:`198`: allows arbitrary Boolean expressions in search query filters.
 - :issue:`226`: allows creating APIs before initializing the Flask application object.
-- :issue:`274`: adds the :func:`url_for` function for computing URLs from models.
+- :issue:`274`: adds the :func:`.url_for` function for computing URLs from models.
 - :issue:`379`: improves datetime parsing in search requests.
 - :issue:`398`: fixes bug where DELETE_SINGLE processors were not actually used.
 - :issue:`400`: disallows excluding a primary key on a :http:method:`POST` request.
@@ -101,7 +103,7 @@ Released on February 3, 2015.
 
 - :issue:`237`: allows bulk delete of model instances via the ``allow_delete_many``
   keyword argument.
-- :issue:`313,389`: :meth:`APIManager.init_app` now can be correctly used to
+- :issue:`313,389`: :meth:`.APIManager.init_app` now can be correctly used to
   initialize multiple Flask applications.
 - :issue:`327,391`: allows ordering searches by fields on related instances.
 - :issue:`353`: allows search queries to specify ``group_by`` directives.
@@ -114,10 +116,11 @@ Version 0.15.1
 
 Released on January 2, 2015.
 
-- :issue:`367`: catch :exc:`IntegrityError`, :exc:`DataError`, and
-  :exc:`ProgrammingError` exceptions in all view methods.
-- :issue:`374`: import :class:`sqlalchemy.Column` from :mod:`sqlalchemy` directly,
-  instead of :mod:`sqlalchemy.sql.schema`
+- :issue:`367`: catch :exc:`sqlalchemy.exc.IntegrityError`,
+  :exc:`sqlalchemy.exc.DataError`, and :exc:`sqlalchemy.exc.ProgrammingError`
+  exceptions in all view methods.
+- :issue:`374`: import :class:`sqlalchemy.schema.Column` from
+  :mod:`!sqlalchemy` directly, instead of :mod:`!sqlalchemy.sql.schema`.
 
 Version 0.15.0
 ~~~~~~~~~~~~~~
@@ -167,7 +170,7 @@ Released on August 12, 2014.
   something is actuall deleted.
 - :issue:`325`: support ``null`` inside ``has`` search operators.
 - :issue:`328`: enable automatic testing for Python 3.4.
-- :issue:`333`: enforce limit in :func:`helpers.count`.
+- :issue:`333`: enforce limit in :func:`!flask_restless.views.helpers.count`.
 - :issue:`338`: catch validation exceptions when attempting to update relations.
 - :issue:`339`: use user-specified primary key on :http:method:`patch` requests.
 - :issue:`344`: correctly encodes Unicode fields in responses.
@@ -209,7 +212,7 @@ Released on April 6, 2014.
 - :issue:`284`: catch ``DataError`` and ``ProgrammingError`` exceptions when bad data
   are sent to the server.
 - :issue:`286`: speed up paginated responses by using optimized count() function.
-- :issue:`293`: allows :class:`sqlalchemy.Time` fields in JSON responses.
+- :issue:`293`: allows :class:`sqlalchemy.types.Time` fields in JSON responses.
 
 Version 0.12.1
 ~~~~~~~~~~~~~~
@@ -255,7 +258,7 @@ Released on May 18, 2013.
   to a dictionary.
 - :issue:`202`: allow setting hybrid properties with expressions and setters.
 - :issue:`203`: adds the ``include_methods`` keyword argument to
-  :meth:`APIManager.create_api`, which allows JSON responses to include the
+  :meth:`.APIManager.create_api`, which allows JSON responses to include the
   result of calling arbitrary methods of instances of models.
 - :issue:`204`, 205: allow parameters in ``Content-Type`` header.
 
@@ -335,7 +338,7 @@ Version 0.9.0
 Released on January 16, 2013.
 
 - Removed ability to provide a :class:`~sqlalchemy.orm.session.Session` class
-  when initializing :class:`APIManager`; provide an instance of the class
+  when initializing :class:`.APIManager`; provide an instance of the class
   instead.
 - Changes some dynamically loaded relationships used for testing and in
   examples to be many-to-one instead of the incorrect one-to-many. Versions of
@@ -344,13 +347,14 @@ Released on January 16, 2013.
 - :issue:`107`: server responds with an error code when a :http:method:`patch` or
   :http:method:`post` request specifies a field which does not exist on the
   model.
-- :issue:`108`: dynamically loaded relationships should now be rendered correctly by
-  the :func:`views._to_dict` function regardless of whether they are a list or
-  a single object.
+- :issue:`108`: dynamically loaded relationships should now be rendered
+  correctly by the :func:`!views._to_dict` function regardless of whether they
+  are a list or a single object.
 - :issue:`109`: use `sphinxcontrib-issuetracker`_ to render links to GitHub issues in
   documentation.
-- :issue:`110`: enable ``results_per_page`` query parameter for clients, and added
-  ``max_results_per_page`` keyword argument to :meth:`APIManager.create_api`.
+- :issue:`110`: enable ``results_per_page`` query parameter for clients, and
+  added ``max_results_per_page`` keyword argument to
+  :meth:`.APIManager.create_api`.
 - :issue:`114`: fix bug where string representations of integers were converted to
   integers.
 - :issue:`117`: allow adding related instances on :http:method:`patch` requests for
@@ -365,8 +369,8 @@ Version 0.8.0
 
 Released on November 19, 2012.
 
-- :issue:`94`: :func:`views._to_dict` should return a single object instead of a list
-  when resolving dynamically loaded many-to-one relationships.
+- :issue:`94`: :func:`!views._to_dict` should return a single object instead of
+  a list when resolving dynamically loaded many-to-one relationships.
 - :issue:`104`: added ``num_results`` key to paginated JSON responses.
 
 Version 0.7.0
@@ -375,19 +379,19 @@ Version 0.7.0
 Released on October 9, 2012.
 
 - Added working ``include`` and ``exclude`` functionality to the
-  :func:`views._to_dict` function.
-- Added ``exclude_columns`` keyword argument to :meth:`APIManager.create_api`.
+  :func:`!views._to_dict` function.
+- Added ``exclude_columns`` keyword argument to :meth:`.APIManager.create_api`.
 - :issue:`79`: attempted to access attribute of ``None`` in constructor of
-  :class:`APIManager`.
+  :class:`.APIManager`.
 - :issue:`83`: allow :http:method:`post` requests with one-to-one related instances.
 - :issue:`86`: allow specifying include and exclude for related models.
 - :issue:`91`: correctly handle :http:method:`post` requests to nullable
-  :class:`~sqlalchemy.DateTime` columns.
+  :class:`~sqlalchemy.types.DateTime` columns.
 - :issue:`93`: Added a ``total_pages`` mapping to the JSON response.
 - :issue:`98`: :http:method:`get` requests to the function evaluation endpoint should
   not have a data payload.
-- :issue:`101`: ``exclude`` in :func:`views._to_dict` function now correctly excludes
-  requested fields from the returned dictionary.
+- :issue:`101`: ``exclude`` in :func:`!views._to_dict` function now correctly
+  excludes requested fields from the returned dictionary.
 
 Version 0.6
 ~~~~~~~~~~~
@@ -401,10 +405,10 @@ Released on June 20, 2012.
 - Fixed issue due to symbolic link from :file:`README` to :file:`README.md`
   when running ``pip bundle foobar Flask-Restless``.
 - Separated API blueprint creation from registration, using
-  :meth:`APIManager.create_api` and :meth:`APIManager.create_api_blueprint`.
+  :meth:`.APIManager.create_api` and :meth:`.APIManager.create_api_blueprint`.
 - Added support for pure SQLAlchemy in addition to Flask-SQLAlchemy.
 - :issue:`74`: Added ``post_form_preprocessor`` keyword argument to
-  :meth:`APIManager.create_api`.
+  :meth:`.APIManager.create_api`.
 - :issue:`77`: validation errors are now correctly handled on :http:method:`PATCH`
   requests.
 
@@ -417,9 +421,9 @@ Released on April 10, 2012.
 - Added capturing of exceptions raised during field validation.
 - Added :file:`examples/separate_endpoints.py`, showing how to create separate
   API endpoints for a single model.
-- Added ``include_columns`` keyword argument to
-  :meth:`~flask_restless.APIManager.create_api` method to allow users to
-  specify which columns of the model are exposed in the API.
+- Added ``include_columns`` keyword argument to :meth:`.APIManager.create_api`
+  method to allow users to specify which columns of the model are exposed in
+  the API.
 - Replaced Elixir with Flask-SQLAlchemy. Flask-Restless now only supports
   Flask-SQLAlchemy.
 
@@ -433,18 +437,15 @@ Released on March 29, 2012.
   authentication and how that authentication will take place.
 - Created base classes for test cases.
 - Moved the ``evaluate_functions`` function out of the
-  :mod:`flask_restless.search` module and corrected documentation about how
+  :mod:`!flask_restless.search` module and corrected documentation about how
   function evaluation works.
-- Added `allow_functions` keyword argument to
-  :meth:`~flask_restless.APIManager.create_api`.
+- Added `allow_functions` keyword argument to :meth:`.APIManager.create_api`.
 - Fixed bug where we weren't allowing PUT requests in
-  :meth:`~flask_restless.manager.APIManager.create_api`.
-- Added ``collection_name`` keyword argument to
-  :meth:`~flask_restless.APIManager.create_api` to allow user provided names in
-  URLs.
-- Added ``allow_patch_many`` keyword argument to
-  :meth:`~flask_restless.APIManager.create_api` to allow enabling or disabling
-  the PATCH many functionality.
+  :meth:`.APIManager.create_api`.
+- Added ``collection_name`` keyword argument to :meth:`.APIManager.create_api`
+  to allow user provided names in URLs.
+- Added ``allow_patch_many`` keyword argument to :meth:`.APIManager.create_api`
+  to allow enabling or disabling the PATCH many functionality.
 - Disable the PATCH many functionality by default.
 
 Version 0.3

docs/api.rst

@@ -10,12 +10,10 @@ The API Manager class
 ---------------------
 
 .. autoclass:: APIManager
+   :members: init_app, create_api, create_api_blueprint
 
-   .. automethod:: init_app
+.. autoclass:: IllegalArgumentError
 
-   .. automethod:: create_api
-
-   .. automethod:: create_api_blueprint
 
 Global helper functions
 -----------------------
@@ -34,12 +32,19 @@ Serialization and deserialization
 ---------------------------------
 
 .. autoclass:: DefaultSerializer
+   :members: serialize, serialize_many
 
 .. autoclass:: DefaultDeserializer
+   :members: deserialize
 
 .. autoclass:: SerializationException
 
 .. autoclass:: DeserializationException
+   :members: message, detail, status
+
+.. autofunction:: simple_serialize
+
+.. autofunction:: simple_serialize_many
 
 .. autoclass:: MultipleExceptions
 

docs/basicusage.rst

@@ -9,8 +9,7 @@ If you have defined your models with Flask-SQLAlchemy, first, create your
 :class:`~flask.Flask` object, :class:`~flask_sqlalchemy.SQLAlchemy` object, and
 model classes as usual but with one additional restriction: each model must
 have a primary key column named ``id`` of type
-:class:`~sqlalchemy.sql.sqltypes.Integer` or type
-:class:`~sqlalchemy.sql.sqltypes.Unicode`.
+:class:`~sqlalchemy.types.Integer` or type :class:`~sqlalchemy.types.Unicode`.
 
 .. sourcecode:: python
 
@@ -63,7 +62,7 @@ If you are using pure SQLAlchemy::
 
    Base.metadata.create_all()
 
-Second, instantiate an :class:`APIManager` object with the
+Second, instantiate an :class:`.APIManager` object with the
 :class:`~flask.Flask` and :class:`~flask_sqlalchemy.SQLAlchemy` objects::
 
     from flask_restless import APIManager
@@ -87,7 +86,7 @@ the endpoints created at this step; for more information, see
 :doc:`customizing`.
 
 Due to the design of Flask, these APIs must be created before your application
-handles any requests. The return value of :meth:`APIManager.create_api` is the
+handles any requests. The return value of :meth:`.APIManager.create_api` is the
 blueprint in which the endpoints for the specified database model live. The
 blueprint has already been registered on the :class:`~flask.Flask` application,
 so you do *not* need to register it yourself. It is provided so that you can
@@ -99,7 +98,7 @@ examine its attributes, but if you don't need it then just ignore it::
 
 If you wish to create the blueprint for the API without registering it (for
 example, if you wish to register it manually later in your code), use the
-:meth:`~APIManager.create_api_blueprint` method instead. You *must* provide an
+:meth:`~.APIManager.create_api_blueprint` method instead. You *must* provide an
 additional positional argument, *name*, to this method::
 
     blueprint = manager.create_api_blueprint('person', Person, methods=methods)
@@ -176,22 +175,22 @@ of ``Person.__tablename__``::
       }
     }
 
-If the primary key is a :class:`~sqlalchemy.Unicode` instead of an
-:class:`~sqlalchemy.Integer`, the instances will be accessible at URL endpoints
-like ``http://<host>:<port>/api/person/foo`` instead of
+If the primary key is a :class:`~sqlalchemy.types.Unicode` instead of an
+:class:`~sqlalchemy.types.Integer`, the instances will be accessible at URL
+endpoints like ``http://<host>:<port>/api/person/foo`` instead of
 ``http://<host>:<port>/api/person/1``.
 
 Deferred API registration
 -------------------------
 
 If you only wish to create APIs on a single Flask application and have access
 to the Flask application before you create the APIs, you can provide a Flask
-application as an argument to the constructor of the :class:`APIManager` class,
-as described above. However, if you wish to create APIs on multiple Flask
-applications or if you do not have access to the Flask application at the time
-you create the APIs, you can use the :meth:`APIManager.init_app` method.
+application as an argument to the constructor of the :class:`.APIManager`
+class, as described above. However, if you wish to create APIs on multiple
+Flask applications or if you do not have access to the Flask application at the
+time you create the APIs, you can use the :meth:`.APIManager.init_app` method.
 
-If a :class:`APIManager` object is created without a Flask application, ::
+If a :class:`.APIManager` object is created without a Flask application, ::
 
     manager = APIManager(session=session)
 
@@ -201,7 +200,7 @@ application::
     manager.create_api(Person)
     manager.create_api(Article)
 
-Later, you can call the :meth:`~APIManager.init_app` method with any
+Later, you can call the :meth:`~.APIManager.init_app` method with any
 :class:`~flask.Flask` objects on which you would like the APIs to be
 available::
 
@@ -211,11 +210,11 @@ available::
     manager.init_app(app2)
 
 The manager creates and stores a blueprint each time
-:meth:`~APIManager.create_api` is invoked, and registers those blueprints each
-time :meth:`~APIManager.init_app` is invoked. (The name of each blueprint will
+:meth:`~.APIManager.create_api` is invoked, and registers those blueprints each
+time :meth:`~.APIManager.init_app` is invoked. (The name of each blueprint will
 be a :class:`uuid.UUID`.)
 
 .. versionchanged:: 1.0.0
 
-   The behavior of the :meth:`~APIManager.init_app` method was strange and
+   The behavior of the :meth:`~.APIManager.init_app` method was strange and
    incorrect before version 1.0.0. It is best not to use earlier versions.

docs/conf.py

@@ -259,11 +259,12 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
-    'python': ('http://docs.python.org/', None),
     'flask': ('http://flask.pocoo.org/docs', None),
-    'sqlalchemy': ('http://docs.sqlalchemy.org/en/latest', None),
+    'flasklogin': ('https://flask-login.readthedocs.io/en/latest', None),
     'flasksqlalchemy': ('http://flask-sqlalchemy.pocoo.org', None),
-    'flasklogin': ('https://flask-login.readthedocs.org/en/latest', None)
+    'python3': ('https://docs.python.org/3', None),
+    'sqlalchemy': ('http://docs.sqlalchemy.org/en/latest', None),
+    'werkzeug': ('http://werkzeug.pocoo.org/docs', None),
 }
 
 # fall back if theme is not there

docs/creating.rst

@@ -66,7 +66,7 @@ yields the response
    }
 
 To create a new resource with a client-generated ID (if enabled by setting
-``allow_client_generated_ids`` to ``True`` in :meth:`APIManager.create_api`),
+``allow_client_generated_ids`` to ``True`` in :meth:`.APIManager.create_api`),
 the request
 
 .. sourcecode:: http