Fix docs warnings

Makefile

@@ -53,6 +53,7 @@ loadtest-check-simulation:
 clean:
 	find . -name '*.pyc' -delete
 	find . -name '__pycache__' -type d | xargs rm -fr
+	rm -fr docs/_build/
 
 distclean: clean
 	rm -fr *.egg *.egg-info/ dist/ build/
@@ -61,6 +62,6 @@ maintainer-clean: distclean
 	rm -fr .venv/ .tox/
 
 docs: install-dev
-	$(VENV)/bin/sphinx-build -n -b html -d $(SPHINX_BUILDDIR)/doctrees cliquet_docs $(SPHINX_BUILDDIR)/html
+	$(VENV)/bin/sphinx-build -a -n -b html -d $(SPHINX_BUILDDIR)/doctrees cliquet_docs $(SPHINX_BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(SPHINX_BUILDDIR)/html/index.html"

cliquet/resource/__init__.py

@@ -129,7 +129,7 @@ class BaseResource(object):
 
     default_model = Model
     """Default :class:`cliquet.resource.model.Model` class to use for
-    interacting the :module:`cliquet.storage` and :module:`cliquet.permission`
+    interacting the :mod:`cliquet.storage` and :mod:`cliquet.permission`
     backends."""
 
     mapping = ResourceSchema()

cliquet/storage/memory.py

@@ -146,7 +146,7 @@ def extract_record_set(self, collection_id, records,
         return sorted_, total_records - filtered_deleted
 
 
-class Memory(MemoryBasedStorage):
+class Storage(MemoryBasedStorage):
     """Storage backend implementation in memory.
 
     Useful for development or testing purposes, but records are lost after
@@ -157,7 +157,7 @@ class Memory(MemoryBasedStorage):
         cliquet.storage_backend = cliquet.storage.memory
     """
     def __init__(self, *args, **kwargs):
-        super(Memory, self).__init__(*args, **kwargs)
+        super(Storage, self).__init__(*args, **kwargs)
         self.flush()
 
     def flush(self, auth=None):
@@ -334,4 +334,4 @@ def column(first, record, name):
 
 
 def load_from_config(config):
-    return Memory()
+    return Storage()

cliquet/storage/redis.py

@@ -21,7 +21,7 @@ def wrapped(*args, **kwargs):
     return wrapped
 
 
-class Redis(MemoryBasedStorage):
+class Storage(MemoryBasedStorage):
     """Storage backend implementation using Redis.
 
     .. warning::
@@ -43,7 +43,7 @@ class Redis(MemoryBasedStorage):
     """
 
     def __init__(self, *args, **kwargs):
-        super(Redis, self).__init__(*args, **kwargs)
+        super(Storage, self).__init__(*args, **kwargs)
         maxconn = kwargs.pop('max_connections')
         connection_pool = redis.BlockingConnectionPool(max_connections=maxconn)
         self._client = redis.StrictRedis(connection_pool=connection_pool,
@@ -295,8 +295,8 @@ def load_from_config(config):
     uri = urlparse.urlparse(uri)
     pool_size = int(settings['storage_pool_size'])
 
-    return Redis(max_connections=pool_size,
-                 host=uri.hostname or 'localhost',
-                 port=uri.port or 6739,
-                 password=uri.password or None,
-                 db=int(uri.path[1:]) if uri.path else 0)
+    return Storage(max_connections=pool_size,
+                   host=uri.hostname or 'localhost',
+                   port=uri.port or 6739,
+                   password=uri.password or None,
+                   db=int(uri.path[1:]) if uri.path else 0)

cliquet/tests/resource/__init__.py

@@ -10,7 +10,7 @@ class BaseTest(unittest.TestCase):
     resource_class = BaseResource
 
     def setUp(self):
-        self.storage = memory.Memory()
+        self.storage = memory.Storage()
         self.resource = self.resource_class(request=self.get_request(),
                                             context=self.get_context())
         self.model = self.resource.model

cliquet/tests/resource/test_views.py

@@ -643,7 +643,7 @@ def __init__(self, *args, **kwargs):
         super(StorageErrorTest, self).__init__(*args, **kwargs)
         self.error = storage_exceptions.BackendError(ValueError())
         self.storage_error_patcher = mock.patch(
-            'cliquet.storage.redis.Redis.create',
+            'cliquet.storage.redis.Storage.create',
             side_effect=self.error)
 
     def test_backend_errors_are_served_as_503(self):

cliquet_docs/api/resource.rst

@@ -356,7 +356,7 @@ Since some fields can be :ref:`defined as unique <resource-class>` per collectio
 
 If a conflict occurs, an error response is returned with status ``409``.
 A ``details`` attribute in the response provides the offending record and
-field name. See :ref:`dedicated section about errors <error-responses>`_.
+field name. See :ref:`dedicated section about errors <error-responses>`.
 
 
 HTTP Status Codes

cliquet_docs/ecosystem.rst

@@ -71,7 +71,7 @@ Alternatively, packages can also be included via configuration:
                        pyramid_debugtoolbar
 
 
-There are `many available packages`_, and it is straightforward to build one.
+There are `many available packages <curated list>`_, and it is straightforward to build one.
 
 .. _curated list: https://github.com/ITCase/awesome-pyramid
 

cliquet_docs/reference/configuration.rst

@@ -57,8 +57,7 @@ To do so, a setting key must be defined for the disabled resources endpoints::
 
 Where:
 - **endpoint_type** is either collection or record;
-- **resource_name** is the name of the resource (by default, *Cliquet* uses
-  the name of the class);
+- **resource_name** is the name of the resource (by default, *Cliquet* uses the name of the class);
 - **method** is the http method (in lower case): For instance ``put``.
 
 For instance, to disable the PUT on records for the *Mushrooms* resource, the
@@ -272,7 +271,7 @@ Cache
 =====
 
 Backend
--------
+:::::::
 
 .. code-block:: ini
 
@@ -286,7 +285,7 @@ See :ref:`cache backend documentation <cache>` for more details.
 
 
 Headers
--------
+:::::::
 
 It is possible to add cache control headers on a particular resource
 for anonymous requests.
@@ -307,7 +306,7 @@ If setting is set to ``0``, then the resource follows the default behaviour.
 
 
 CORS
-----
+::::
 
 By default, CORS headers are cached by clients during 1H (``Access-Control-Max-Age``).
 
@@ -336,7 +335,7 @@ in configuration:
 Authentication setup
 ::::::::::::::::::::
 
-*Cliquet* relies on :github:`pyramid multiauth <mozilla-service/pyramid_multiauth>`_
+*Cliquet* relies on :github:`pyramid multiauth <mozilla-service/pyramid_multiauth>`
 to initialize authentication.
 
 Therefore, any authentication policy can be specified through configuration.

cliquet_docs/reference/resource.rst

@@ -1,8 +1,8 @@
+.. _resource:
+
 Resource
 ########
 
-.. _resource:
-
 *Cliquet* provides a basic component to build resource oriented APIs.
 In most cases, the main customization consists in defining the schema of the
 records for this resource.
@@ -100,7 +100,7 @@ a custom collection can be plugged-in:
         default_model = TrackedModel
 
 
-.. _collection:
+.. _resource-model:
 
 .. autoclass:: cliquet.resource.Model
     :members:

cliquet_docs/reference/storage.rst

@@ -54,4 +54,4 @@ Storage can be used to store arbitrary data.
     storage = request.registry.storage
     storage.create(collection_id='__custom', parent_id='', record=data)
 
-See the :ref:`collection` class to manipulate collections of records.
+See the :ref:`resource-model` class to manipulate collections of records.