Add declarative catalog docs

docs/catalogs/bundles.rst

@@ -1,5 +1,5 @@
-Creating catalog provider bundles
----------------------------------
+Catalog provider bundles
+------------------------
 
 ``di.DeclarativeCatalog.Bundle`` is a limited collection of catalog providers. 
 While catalog could be used as a centralized place for particular providers 

docs/catalogs/declarative.rst

@@ -0,0 +1,65 @@
+Declarative catalogs
+--------------------
+
+``di.DeclarativeCatalog`` is a catalog of providers that could be defined in 
+declarative manner. It should cover most of the cases when list of providers 
+that would be included in catalog is deterministic (catalog will not change 
+its structure in runtime).
+
+Definition of declarative catalogs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Declarative catalogs have to extend base declarative catalog class - 
+``di.DeclarativeCatalog``.
+
+Providers have to be defined like catalog's class attributes. Every provider in
+catalog has name. This name should follow ``some_provider`` convention, 
+that is standard naming convention for attribute names in Python.
+
+.. note::
+
+    It might be useful to add such ``""":type: di.Provider -> Object1"""`` 
+    docstrings just on the next line after provider's definition.  It will 
+    help code analyzing tools and IDE's to understand that variable above 
+    contains some callable object, that returns particular instance as a 
+    result of its call.
+
+Here is an simple example of declarative catalog with several factories:
+
+.. image:: /images/catalogs/declarative.png
+    :width: 85%
+    :align: center
+
+.. literalinclude:: ../../examples/catalogs/declarative.py
+   :language: python
+
+Declarative catalogs API
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+``di.DeclarativeCatalog`` has several features that could be useful for some 
+kind of operations on catalog's providers:
+
+- ``di.DeclarativeCatalog.providers`` is read-only attribute that contains 
+  ``dict`` of all catalog providers, including providers that are inherited 
+  from parent catalogs, where key is the name of provider and value is 
+  provider itself.
+- ``di.DeclarativeCatalog.cls_providers`` is read-only attribute contains 
+  ``dict`` of current catalog providers, where key is the name of provider 
+  and value is provider itself.
+- ``di.DeclarativeCatalog.inherited_providers`` is read-only attribute 
+  contains ``dict`` of all providers that are inherited from parent catalogs, 
+  where key is the name of provider and value is provider itself. 
+- ``di.DeclarativeCatalog.filter(provider_type=di.Provider)`` is a class 
+  method that could be used for filtering catalog providers by provider types 
+  (for example, for getting all ``di.Factory`` providers). 
+  ``di.DeclarativeCatalog.filter()`` method use 
+  ``di.DeclarativeCatalog.providers``.
+
+Example:
+
+.. image:: /images/catalogs/declarative_api.png
+    :width: 100%
+    :align: center
+
+.. literalinclude:: ../../examples/catalogs/declarative_api.py
+   :language: python

docs/catalogs/dynamic.rst

@@ -0,0 +1,2 @@
+Dynamic catalogs
+----------------

docs/catalogs/index.rst

@@ -19,7 +19,7 @@ of providers.
 ..  toctree::
     :maxdepth: 2
 
-    writing
-    operating
+    declarative
+    dynamic
     bundles
     overriding

docs/catalogs/operating.rst

@@ -1,30 +0,0 @@
-Operating with catalogs
------------------------
-
-``di.DeclarativeCatalog`` has several features that could be useful for some 
-kind of operations on catalog's providers:
-
-- ``di.DeclarativeCatalog.providers`` is read-only attribute that contains 
-  ``dict`` of all catalog providers, including providers that are inherited 
-  from parent catalogs, where key is the name of provider and value is 
-  provider itself.
-- ``di.DeclarativeCatalog.cls_providers`` is read-only attribute contains 
-  ``dict`` of current catalog providers, where key is the name of provider 
-  and value is provider itself.
-- ``di.DeclarativeCatalog.inherited_providers`` is read-only attribute 
-  contains ``dict`` of all providers that are inherited from parent catalogs, 
-  where key is the name of provider and value is provider itself. 
-- ``di.DeclarativeCatalog.filter(provider_type=di.Provider)`` is a class 
-  method that could be used for filtering catalog providers by provider types 
-  (for example, for getting all ``di.Factory`` providers). 
-  ``di.DeclarativeCatalog.filter()`` method use 
-  ``di.DeclarativeCatalog.providers``.
-
-Example:
-
-.. image:: /images/catalogs/operating_with_providers.png
-    :width: 100%
-    :align: center
-
-.. literalinclude:: ../../examples/catalogs/operating_with_providers.py
-   :language: python

docs/catalogs/writing.rst

@@ -1,25 +0,0 @@
-Writing catalogs
-----------------
-
-Catalogs have to extend base catalog class ``di.DeclarativeCatalog``.
-
-Providers have to be defined like catalog's attributes. Every provider in
-catalog has name. This name should follow ``some_provider`` convention, 
-that is standard naming convention for attribute names in Python.
-
-.. note::
-
-    It might be useful to add such ``""":type: di.Provider -> Object1"""`` 
-    docstrings just on the next line after provider's definition.  It will 
-    help code analyzing tools and IDE's to understand that variable above 
-    contains some callable object, that returns particular instance as a 
-    result of its call.
-
-Here is an simple example of catalog with several factories:
-
-.. image:: /images/catalogs/writing_catalogs.png
-    :width: 85%
-    :align: center
-
-.. literalinclude:: ../../examples/catalogs/writing_catalogs.py
-   :language: python

docs/conf.py

@@ -28,7 +28,7 @@ import re
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = ['sphinx.ext.autodoc']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/providers/custom.rst

@@ -1,4 +1,4 @@
-Writing custom providers
+Writing of custom providers
 ------------------------
 
 List of *Dependency Injector* providers could be widened with custom providers.

examples/catalogs/declarative.py

@@ -1,4 +1,4 @@
-"""Catalog example."""
+"""Declarative catalog example."""
 
 import dependency_injector as di
 

examples/catalogs/declarative_api.py

@@ -1,4 +1,4 @@
-"""Operating with catalog providers example."""
+"""Declarative catalog API example."""
 
 import dependency_injector as di