From 4edce19176898736fc4914b7eb08d907566f0547 Mon Sep 17 00:00:00 2001 From: Stephen Burrows Date: Fri, 28 Jan 2011 17:03:05 -0500 Subject: [PATCH] Added structure for model documentation, as well as writing the documentation for the Node and View classes. Set up .gitignore to not worry about the docs build directory. --- .gitignore | 1 + docs/conf.py | 2 +- docs/index.rst | 1 + docs/models/entities.rst | 2 ++ docs/models/intro.rst | 13 ++++++++ docs/models/nodes-and-views.rst | 54 +++++++++++++++++++++++++++++++++ 6 files changed, 72 insertions(+), 1 deletion(-) create mode 100644 docs/models/entities.rst create mode 100644 docs/models/intro.rst create mode 100644 docs/models/nodes-and-views.rst diff --git a/.gitignore b/.gitignore index 0d20b64..073067c 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ *.pyc +docs/_build/ diff --git a/docs/conf.py b/docs/conf.py index f998dea..a879f03 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -25,7 +25,7 @@ sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "_ext")) # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.coverage', 'djangodocs'] +extensions = ['djangodocs'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/docs/index.rst b/docs/index.rst index 76e779d..cfc7136 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,6 +12,7 @@ Contents: :maxdepth: 2 intro + models/intro Indices and tables ================== diff --git a/docs/models/entities.rst b/docs/models/entities.rst new file mode 100644 index 0000000..f381ead --- /dev/null +++ b/docs/models/entities.rst @@ -0,0 +1,2 @@ +Entities: the base class +======================== \ No newline at end of file diff --git a/docs/models/intro.rst b/docs/models/intro.rst new file mode 100644 index 0000000..49b2ac1 --- /dev/null +++ b/docs/models/intro.rst @@ -0,0 +1,13 @@ +Philo's models +============== + +Contents: + +.. toctree:: + :maxdepth: 2 + + entities + nodes-and-views + + +.. :module: philo.models diff --git a/docs/models/nodes-and-views.rst b/docs/models/nodes-and-views.rst new file mode 100644 index 0000000..a9bae89 --- /dev/null +++ b/docs/models/nodes-and-views.rst @@ -0,0 +1,54 @@ +Nodes and Views: Building Website structure +=========================================== +.. currentmodule:: philo.models +.. class:: Node + + .. attribute:: view + + :class:`GenericForeignKey` to a non-abstract subclass of :class:`View` + + .. attribute:: accepts_subpath + + A property shortcut for :attr:`self.view.accepts_subpath ` + + .. method:: render_to_response(request[, extra_context=None]) + + This is a shortcut method for :meth:`View.render_to_response` + + .. method:: get_absolute_url() + + As long as :mod:`philo.urls` is included somewhere in the urlpatterns, this will return the URL of this node. The returned value will always start and end with a slash. + +.. class:: View + + :class:`!View` is an abstract model that represents an item which can be "rendered", either in response to an :class:`HttpRequest` or as a standalone. + + .. attribute:: accepts_subpath + + Defines whether this View class can handle subpaths. + + .. attribute:: nodes + + A generic relation back to nodes. + + .. method:: get_subpath(obj) + + If the view :attr:`accepts subpaths <.accepts_subpath>`, try to find a reversal for the given object using ``self`` as the urlconf. This method calls :meth:`~.get_reverse_params` with ``obj`` as the argument to find out the reversing parameters for that object. + + .. method:: get_reverse_params(obj) + + This method should return a ``view_name``, ``args``, ``kwargs`` tuple suitable for reversing a url for the given ``obj`` using ``self`` as the urlconf. + + .. method:: attributes_with_node(node) + + Returns a :class:`QuerySetMapper` using the :class:`node `'s attributes as a passthrough. + + .. method:: render_to_response(request[, extra_context=None]) + + Renders the :class:`View` as an :class:`HttpResponse`. This will raise :const:`philo.exceptions.MIDDLEWARE_NOT_CONFIGURED` if the `request` doesn't have an attached :class:`Node`. This can happen if :class:`philo.middleware.RequestNodeMiddleware` is not in :setting:`settings.MIDDLEWARE_CLASSES` or if it is not functioning correctly. + + :meth:`!render_to_response` will send the :obj:`view_about_to_render ` signal, then call :meth:`actually_render_to_response`, and finally send the :obj:`view_finished_rendering ` signal before returning the ``response``. + + .. method:: actually_render_to_response(request[, extra_context=None]) + + Concrete subclasses must override this method to provide the business logic for turning a ``request`` and ``extra_context`` into an :class:`HttpResponse`. \ No newline at end of file -- 2.20.1