Merge pull request #38 from pstch/routers

Improved documentation
pstch · Jun 26, 2014 · d9f5b09 · d9f5b09
2 parents 760a5cc + 6701012
commit d9f5b09
Show file tree

Hide file tree

Showing 18 changed files with 90 additions and 157 deletions.
diff --git a/django_crucrudile/entity/__init__.py → django_crucrudile/entities/__init__.py b/django_crucrudile/entity/__init__.py → django_crucrudile/entities/__init__.py
@@ -4,9 +4,10 @@
 class Entity(metaclass=ABCMeta):
     """Abstract class for routed entities
 
-    Subclasses should define the abstract :func:`patterns` method, that should
-    return a generator yielding Django URL objects (``RegexURLPattern`` or
-    ``RegexURLResolver``).
+    .. warning:: Abstract class ! Subclasses should define the
+                 abstract :func:`patterns` method, that should return
+                 a generator yielding Django URL objects
+                 (``RegexURLPattern`` or ``RegexURLResolver``).
 
 
     .. inheritance-diagram:: Entity
@@ -23,9 +24,12 @@ def __init__(self, index=None):
 
     @abstractmethod
     def patterns(self, parents=None, add_redirect=True):
-        """This abstract method should be defined by subclasses, as a
-        generator that yields Django URL objects (``RegexURLPattern`` or
-        ``RegexURLResolver``)
+        """Yield URL patterns
+
+        .. warning:: This abstract method should be defined by
+                     subclasses, and should return a generator
+                     yielding Django URL objects (``RegexURLPattern``
+                     or ``RegexURLResolver``)
 
         """
         pass

diff --git a/django_crucrudile/entity/store.py → django_crucrudile/entities/store.py b/django_crucrudile/entity/store.py → django_crucrudile/entities/store.py
@@ -2,8 +2,10 @@
 
 
 def provides(provided, **kwargs):
-    """Return a decorator that uses :func:`EntityStore.register_class` to register a class in
-the base store"""
+    """Return a decorator that uses :func:`EntityStore.register_class` to
+    register a class in the base store
+    """
+
     def register_class_to_router(router):
         """Register the provided class"""
         router.register_class(provided, **kwargs)

diff --git a/django_crucrudile/routers/__init__.py b/django_crucrudile/routers/__init__.py
@@ -13,8 +13,8 @@
 from django.views.generic.list import MultipleObjectMixin
 
 from django_crucrudile.routes import ViewRoute, ModelViewRoute
-from django_crucrudile.entity import Entity
-from django_crucrudile.entity.store import EntityStore, provides
+from django_crucrudile.entities import Entity
+from django_crucrudile.entities.store import EntityStore, provides
 
 __all__ = [
     "Router", "BaseModelRouter",

diff --git a/django_crucrudile/routes/__init__.py b/django_crucrudile/routes/__init__.py
@@ -2,13 +2,15 @@
 
 from django.conf.urls import url
 
-from django_crucrudile.entity import Entity
+from django_crucrudile.entities import Entity
 
 
 class Route(Entity):
     """Abstract class for a :class:`django_crucrudile.entity.Entity` that
-    yields URL patterns. Subclasses should define the
-    :func:`get_callback` function.
+    yields URL patterns.
+
+    .. warning:: Abstract class ! Subclasses should define the
+                 :func:`get_callback` function.
 
     The URL part and URL name must be either set on class, or given at
     :func:`__init__`.

diff --git a/docs/conf.py b/docs/conf.py
@@ -49,7 +49,7 @@
 templates_path = ['_templates']
 
 # The suffix of source filenames.
-source_suffix = '.txt'
+source_suffix = '.rst'
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'

diff --git a/docs/django_crucrudile.entity.txt b/docs/django_crucrudile.entity.txt
diff --git a/docs/django_crucrudile.routers.txt b/docs/django_crucrudile.routers.txt
diff --git a/docs/django_crucrudile.routes.txt b/docs/django_crucrudile.routes.txt
diff --git a/docs/django_crucrudile.txt b/docs/django_crucrudile.txt
diff --git a/docs/entities.rst b/docs/entities.rst
@@ -0,0 +1,7 @@
+Entity (``Entity``)
+===================
+
+.. automodule:: django_crucrudile.entities
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/entities.txt b/docs/entities.txt
diff --git a/docs/entity_store.rst b/docs/entity_store.rst
@@ -0,0 +1,7 @@
+Entity store (``EntityStoreMetaclass``, ``EntityStore`` and ``provides``)
+=========================================================================
+
+.. automodule:: django_crucrudile.entities.store
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/gettingstarted.txt → docs/getting_started.rst b/docs/gettingstarted.txt → docs/getting_started.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -0,0 +1,40 @@
+django-crucrudile
+=================
+
+.. toctree::
+   installation
+   getting_started
+   entity_store
+   entities
+   routers
+   routes
+
+* :ref:`modindex`
+
+Class structure graph
+---------------------
+
+.. graphviz::
+
+   digraph class_structure {
+
+     "Abstract" [color=black, fontcolor=white, style=filled]
+
+     "Entity" [color=black, fontcolor=white, style=filled]
+     "Route" [color=black, fontcolor=white, style=filled]
+     "ModelRoute" [color=black, fontcolor=white, style=filled]
+
+     "Entity" -> "Route"
+     "Entity" -> "Router"
+     "EntityStore" -> "Router"
+
+     "Router" -> "BaseModelRouter"
+     "BaseModelRouter" -> "ModelRouter"
+
+     "Route" -> "ModelRoute"
+     "Route" -> "ViewRoute"
+
+     "ModelRoute" -> "ModelViewRoute"
+     "ViewRoute" -> "ModelViewRoute"
+
+   }
diff --git a/docs/installation.txt → docs/installation.rst b/docs/installation.txt → docs/installation.rst
diff --git a/docs/reference.txt b/docs/reference.txt
diff --git a/docs/routers.rst b/docs/routers.rst
@@ -0,0 +1,7 @@
+Routers (``Router``, ``BaseModelRouter`` and ``ModelRouter``)
+=============================================================
+
+.. automodule:: django_crucrudile.routers
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/routes.rst b/docs/routes.rst
@@ -0,0 +1,7 @@
+Routes (``Route``, ``ModelRoute``, ``ViewRoute`` and ``ModelViewRoute``)
+========================================================================
+
+.. automodule:: django_crucrudile.routes
+    :members:
+    :undoc-members:
+    :show-inheritance: