From ed4db03c7ddeb20fde5f7951ea9895f2aadca42f Mon Sep 17 00:00:00 2001 From: Corey Oordt Date: Mon, 1 Aug 2011 09:48:50 -0400 Subject: [PATCH] Updating the documentation. --- doc_src/index.rst | 10 +- doc_src/reference/index.rst | 1 + doc_src/reference/models.rst | 42 ++++ doc_src/{ => reference}/templatetags.rst | 0 docs/.buildinfo | 4 +- docs/_sources/adding_the_fields.txt | 23 ++ docs/_sources/getting_started.txt | 5 + docs/_sources/index.txt | 10 +- docs/_sources/reference/index.txt | 5 +- .../reference/management_commands.txt | 38 +++ docs/_sources/reference/models.txt | 42 ++++ docs/_sources/reference/templatetags.txt | 146 ++++++++++++ docs/_sources/registering_models.txt | 2 + docs/adding_the_fields.html | 125 ++++++++++ docs/genindex.html | 10 +- docs/getting_started.html | 34 ++- docs/index.html | 30 +-- docs/objects.inv | 8 +- docs/reference/index.html | 39 +++- docs/reference/management_commands.html | 134 +++++++++++ docs/reference/models.html | 146 ++++++++++++ docs/reference/settings.html | 19 +- docs/reference/templatetags.html | 219 ++++++++++++++++++ docs/registering_models.html | 16 +- docs/search.html | 10 +- docs/searchindex.js | 2 +- docs/templatetags.html | 13 +- docs/usage.html | 10 +- 28 files changed, 1056 insertions(+), 87 deletions(-) create mode 100644 doc_src/reference/models.rst rename doc_src/{ => reference}/templatetags.rst (100%) create mode 100644 docs/_sources/adding_the_fields.txt create mode 100644 docs/_sources/reference/management_commands.txt create mode 100644 docs/_sources/reference/models.txt create mode 100644 docs/_sources/reference/templatetags.txt create mode 100644 docs/adding_the_fields.html create mode 100644 docs/reference/management_commands.html create mode 100644 docs/reference/models.html create mode 100644 docs/reference/templatetags.html diff --git a/doc_src/index.rst b/doc_src/index.rst index 75142c0..d78f824 100644 --- a/doc_src/index.rst +++ b/doc_src/index.rst @@ -1,8 +1,6 @@ -=========================================== -Django Categories v|version| documentation! -=========================================== - - +============================= +Django Categories v |version| +============================= Contents: @@ -13,7 +11,7 @@ Contents: getting_started usage registering_models - templatetags + adding_the_fields reference/index Indices and tables diff --git a/doc_src/reference/index.rst b/doc_src/reference/index.rst index 15afed2..9bca020 100644 --- a/doc_src/reference/index.rst +++ b/doc_src/reference/index.rst @@ -9,3 +9,4 @@ Reference management_commands models settings + templatetags diff --git a/doc_src/reference/models.rst b/doc_src/reference/models.rst new file mode 100644 index 0000000..2f66ba8 --- /dev/null +++ b/doc_src/reference/models.rst @@ -0,0 +1,42 @@ +====== +Models +====== + +Category +======== + +**parent** + The category's parent category. Leave this blank for an Category Tree. + +**name** + The name of the category. + +**thumbnail** + An optional thumbnail, that is uploaded to ``CATEGORY_SETTINGS['THUMBNAIL_UPLOAD_PATH']`` via ``CATEGORY_SETTINGS['THUMBNAIL_STORAGE']``\ . + +**thumbnail_width** + The thumbnail width. + +**thumbnail_height** + The thumbnail height. + +**order** + The order of this category in the listing + +**slug** + A slug created from the name field + +**alternate_title** + An alternative title to use on pages with this category. + +**alternate_url** + An alternative URL to use instead of the one derived from the category hierarchy. + +**description** + An optional longer description of the category. + +**meta_keywords** + Comma-separated keywords for search engines. + +**meta_extra** + (Advanced) Any additional HTML to be placed verbatim in the ```` diff --git a/doc_src/templatetags.rst b/doc_src/reference/templatetags.rst similarity index 100% rename from doc_src/templatetags.rst rename to doc_src/reference/templatetags.rst diff --git a/docs/.buildinfo b/docs/.buildinfo index 336f91a..0885fbe 100644 --- a/docs/.buildinfo +++ b/docs/.buildinfo @@ -1,4 +1,4 @@ # Sphinx build info version 1 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. -config: 0f579989dd4cbe4af0af63fb63e64641 -tags: fbb0d17656682115ca4d033fb2f83ba1 +config: +tags: diff --git a/docs/_sources/adding_the_fields.txt b/docs/_sources/adding_the_fields.txt new file mode 100644 index 0000000..a6a920f --- /dev/null +++ b/docs/_sources/adding_the_fields.txt @@ -0,0 +1,23 @@ +.. _adding_the_fields: + +================================= +Adding the fields to the database +================================= + +While Django will create the appropriate columns and tables if you configure Django Categories first, many times that is not possible. You could also reset the table, but you would loose all data in it. There is another way. + +Enter South +*********** + +`South `_ is a Django application for managing database schema changes. South's default behavior is for managing permanent changes to a model's structure. In the case of dynamically adding a field or fields to a model, this doesn't work because you are not making the change permanent. And probably don't want to. + +Django Categories has a management command to create any missing fields. It requires South because it uses the South's API for making changes to databases. The management command is simple: ``python manage.py add_category_fields [app]``\ . If you do not include an app name, it will attempt to do all applications configured. + +Running this command several times will not hurt any data or cause any errors. + +Reconfiguring Fields +******************** + +You can make changes to the field configurations as long as they do not change the underlying database structure. For example, adding a ``related_name`` (see :ref:`registering_a_m2one_relationship`\ ) because it only affects Django code. Changing the name of the field, however, is a different matter. + +Django Categories provides a complementary management command to drop a field from the database (the field must still be in the configuration to do so): ``python manage.py drop_category_field app_name model_name field_name`` \ No newline at end of file diff --git a/docs/_sources/getting_started.txt b/docs/_sources/getting_started.txt index e2612a4..954a063 100644 --- a/docs/_sources/getting_started.txt +++ b/docs/_sources/getting_started.txt @@ -54,11 +54,16 @@ Hard coded connections are done in the exact same way you handle any other forei name = models.CharField(max_length=100) category = models.ForeignKey('categories.Category') +Don't forget to add the field or fields to your ``ModelAdmin`` class as well. + .. _lazy_connection: Lazy Connection *************** +Lazy connections are done through configuring Django Categories in the project's ``settings.py`` file. When the project starts up, the configured fields are dynamically added to the configured models and admin. + +If you do this before you have created the database (before you ran ``manage.py syncdb``), the fields will also be in the tables. If you do this after you have already created all the tables, you can run ``manage.py add_category_fields`` to create the fields (this requires Django South to be installed). You add a many-to-one or many-to-many relationship with Django Categories using the ``CATEGORIES_SETTINGS['FK_REGISTRY']`` and ``CATEGORIES_SETTINGS['M2M_REGISTRY']`` settings respectively. For more information see :ref:`registering_models`\ . diff --git a/docs/_sources/index.txt b/docs/_sources/index.txt index 75142c0..d78f824 100644 --- a/docs/_sources/index.txt +++ b/docs/_sources/index.txt @@ -1,8 +1,6 @@ -=========================================== -Django Categories v|version| documentation! -=========================================== - - +============================= +Django Categories v |version| +============================= Contents: @@ -13,7 +11,7 @@ Contents: getting_started usage registering_models - templatetags + adding_the_fields reference/index Indices and tables diff --git a/docs/_sources/reference/index.txt b/docs/_sources/reference/index.txt index bc987c1..9bca020 100644 --- a/docs/_sources/reference/index.txt +++ b/docs/_sources/reference/index.txt @@ -6,4 +6,7 @@ Reference :maxdepth: 2 :glob: - settings \ No newline at end of file + management_commands + models + settings + templatetags diff --git a/docs/_sources/reference/management_commands.txt b/docs/_sources/reference/management_commands.txt new file mode 100644 index 0000000..0339ab1 --- /dev/null +++ b/docs/_sources/reference/management_commands.txt @@ -0,0 +1,38 @@ +.. _management-commands: + +=================== +Management Commands +=================== + +.. _import_categories: + +import_categories +================= + +**Usage:** ``./manage.py import_categories /path/to/file.txt [/path/to/file2.txt]`` + +Imports category tree(s) from a file. Sub categories must be indented by the same multiple of spaces or tabs. The first line in the file cannot start with a space or tab and you can't mix spaces and tabs. + + +.. _add_category_fields: + +add_category_fields +=================== + +**Usage:** ``./manage.py add_category_fields [app1 app2 ...]`` + +Add missing registered category fields to the database table of a specified application or all registered applications. + +Requires Django South. + + +.. _drop_category_fields: + +drop_category_fields +=================== + +**Usage:** ``./manage.py drop_category_field app_name model_name field_name`` + +Drop the ``field_name`` field from the ``app_name_model_name`` table, if the field is currently registered in ``CATEGORIES_SETTINGS``\ . + +Requires Django South. \ No newline at end of file diff --git a/docs/_sources/reference/models.txt b/docs/_sources/reference/models.txt new file mode 100644 index 0000000..2f66ba8 --- /dev/null +++ b/docs/_sources/reference/models.txt @@ -0,0 +1,42 @@ +====== +Models +====== + +Category +======== + +**parent** + The category's parent category. Leave this blank for an Category Tree. + +**name** + The name of the category. + +**thumbnail** + An optional thumbnail, that is uploaded to ``CATEGORY_SETTINGS['THUMBNAIL_UPLOAD_PATH']`` via ``CATEGORY_SETTINGS['THUMBNAIL_STORAGE']``\ . + +**thumbnail_width** + The thumbnail width. + +**thumbnail_height** + The thumbnail height. + +**order** + The order of this category in the listing + +**slug** + A slug created from the name field + +**alternate_title** + An alternative title to use on pages with this category. + +**alternate_url** + An alternative URL to use instead of the one derived from the category hierarchy. + +**description** + An optional longer description of the category. + +**meta_keywords** + Comma-separated keywords for search engines. + +**meta_extra** + (Advanced) Any additional HTML to be placed verbatim in the ```` diff --git a/docs/_sources/reference/templatetags.txt b/docs/_sources/reference/templatetags.txt new file mode 100644 index 0000000..b5463f4 --- /dev/null +++ b/docs/_sources/reference/templatetags.txt @@ -0,0 +1,146 @@ +============= +Template Tags +============= + +get_top_level_categories +======================== + +Retrieves an alphabetical list of all the categories that have no parents. + +Syntax: + +.. code-block:: django + + {% get_top_level_categories as categories %} + +Returns an list of categories ``[, , +
  • Top + +
    • + + + +get_category_drilldown +====================== + +Retrieves the specified category, its ancestors and its immediate children +as an iterable. + +Example: + +.. code-block:: django + + {% get_category_drilldown "/Grandparent/Parent" as family %} + +or + +.. code-block:: django + + {% get_category_drilldown category_obj as family %} + +Sets ``family`` to:: + + [Grandparent, Parent, Child 1, Child 2, Child n] + + +display_drilldown_as_ul +======================= + +Render the category with ancestors and children using the +``categories/ul_tree.html`` template. + +Example: + +.. code-block:: django + + {% display_drilldown_as_ul "/Grandparent/Parent" %} + +or: + +.. code-block:: django + + {% display_drilldown_as_ul category_obj %} + +Returns: + +.. code-block:: html + + + + +breadcrumbs tag +=============== + +Render breadcrumbs, using the ``categories/breadcrumbs.html`` template, using the optional ``separator`` argument. + +Example: + +.. code-block:: django + + {% breadcrumbs "/Grandparent/Parent" %} + +or: + +.. code-block:: django + + {% breadcrumbs category_obj %} + +Returns: + +.. code-block:: html + + Grandparent / Parent + +You can alter the separator used in the template by adding a string argument to be the separator: + +.. code-block:: django + + {% breadcrumbs category_obj "::" %} + +Returns: + +.. code-block:: html + + Grandparent :: Parent diff --git a/docs/_sources/registering_models.txt b/docs/_sources/registering_models.txt index d348093..e44f652 100644 --- a/docs/_sources/registering_models.txt +++ b/docs/_sources/registering_models.txt @@ -95,6 +95,8 @@ Registering one or more Many-to-Many Category fields to a Model } } +.. _registering_a_m2one_relationship: + Registering a many-to-one relationship ====================================== diff --git a/docs/adding_the_fields.html b/docs/adding_the_fields.html new file mode 100644 index 0000000..ff9f6e7 --- /dev/null +++ b/docs/adding_the_fields.html @@ -0,0 +1,125 @@ + + + + + + + + Adding the fields to the database — Django Categories v0.7beta1 documentation + + + + + + + + + + + +
    +

    Django Categories v0.7beta1 documentation

    +
    + + +
    +
    + + + +

    This Page

    + + + +
    +
    + + + +
    +
    +
    +
    + +
    +

    Adding the fields to the database

    +

    While Django will create the appropriate columns and tables if you configure Django Categories first, many times that is not possible. You could also reset the table, but you would loose all data in it. There is another way.

    +
    +

    Enter South

    +

    South is a Django application for managing database schema changes. South’s default behavior is for managing permanent changes to a model’s structure. In the case of dynamically adding a field or fields to a model, this doesn’t work because you are not making the change permanent. And probably don’t want to.

    +

    Django Categories has a management command to create any missing fields. It requires South because it uses the South’s API for making changes to databases. The management command is simple: python manage.py add_category_fields [app]. If you do not include an app name, it will attempt to do all applications configured.

    +

    Running this command several times will not hurt any data or cause any errors.

    +
    +
    +

    Reconfiguring Fields

    +

    You can make changes to the field configurations as long as they do not change the underlying database structure. For example, adding a related_name (see Registering a many-to-one relationship) because it only affects Django code. Changing the name of the field, however, is a different matter.

    +

    Django Categories provides a complementary management command to drop a field from the database (the field must still be in the configuration to do so): python manage.py drop_category_field app_name model_name field_name

    +
    +
    + + +
    +
    +
    +
    +

    + © Copyright 2010, CoreyOordt. + Created using Sphinx 1.0.5. +

    +
    +
    +
    + + + + \ No newline at end of file diff --git a/docs/genindex.html b/docs/genindex.html index 7ac93dd..275ebfa 100644 --- a/docs/genindex.html +++ b/docs/genindex.html @@ -6,13 +6,13 @@ - Index — Django Categories v0.6 documentation + Index — Django Categories v0.7beta1 documentation - +
    -

    Django Categories v0.6 documentation

    +

    Django Categories v0.7beta1 documentation

    diff --git a/docs/index.html b/docs/index.html index bad05dd..9ead7ec 100644 --- a/docs/index.html +++ b/docs/index.html @@ -6,13 +6,13 @@ - Django Categories v|version| documentation! — Django Categories v0.6 documentation + Django Categories v 0.7beta1 — Django Categories v0.7beta1 documentation - +
    -

    Django Categories v0.6 documentation

    +

    Django Categories v0.7beta1 documentation