Commits

Benoît Bryon committed 9d92b24 Draft

Various changes in documentation (mostly fixes and simplification).

  • Participants
  • Parent commits ae54d8d

Comments (0)

Files changed (19)

 Installation
 ############
 
-The code is published under the BSD license. See LICENSE for details.
+The code is published under the BSD license. See :doc:`/about/LICENSE` for
+details.
 
-If you just want to discover the application, have a look at the :doc:`/demo`.
+If you just want to discover the application, you may have a look at the
+:doc:`/demo`.
 
-*********************
-Installation synopsis
-*********************
+If you want to contribute to the code, you should go to :doc:`/contribute`
+documentation.
 
-* Check requirements
-* Get the code
-* Update project settings
 
-************
-Requirements
-************
+**********************
+Install Python package
+**********************
 
-Notice that managing requirements is easier if you choose an automatic
-installation procedure.
+Install the package with your favorite Python installer. As an example, with
+pip:
 
-This application requires:
+.. code-block:: sh
 
-* `Django-1.3`_. The application targets the latest stable release of 
-  branch 1.x. It may work with previous versions, but tests focus on the latest
-  one.
-* `django-templateaddons`_: a set of helpers for the template designer and
-  template tag developer.
+   pip install django-formrenderingtools
 
-.. _`Django-1.3`: http://djangoproject.com/
-.. _`django-templateaddons`: http://bitbucket.org/benoitbryon/django-templateaddons
 
-************
-Get the code
-************
+******************************
+Update Django project settings
+******************************
 
-The code is published under the BSD license. See :doc:`LICENSE` for details.
+Add ``djc.formrenderingtools`` to the ``INSTALLED_APPS`` list in your Django
+project settings:
 
-Latest release
-==============
+.. code-block:: python
 
-This application is known as "django-formrenderingtools" on 
-`Pypi <http://pypi.python.org/>`_. 
+  INSTALLED_APPS = (
+      # ...
+      'djc.formrenderingtools',
+      # ...
+  )
 
-So you can install it with pip or easy_install. As an example::
-
-  # pip install -U django-formrenderingtools
-
-Obviously, you can also add it to your eggs list in a buildout configuration
-file.
-
-Development files
-=================
-
-You can use pip to automatically download and install the project with 
-versionning::
-
-  # pip install -U -e hg+http://bitbucket.org/benoitbryon/django-formrenderingtools#egg=djc.formrenderingtools
-
-Manual installation
-===================
-
-Manual installation is not the recommended way: you'd better learn about
-buildout or virtualenv+pip.
-
-The main project page is http://bitbucket.org/benoitbryon/django-formrenderingtools.
-
-You can clone the repository with the following command line:
-
-.. code-block:: bash
-
-  $ hg clone http://bitbucket.org/benoitbryon/django-formrenderingtools
-
-Copy the django-formrenderingtools/djc folder somewhere in your PYTHON_PATH. It
-may be in your project's directory.
-
-***************
-Update settings
-***************
-
-* add 'djc.formrenderingtools' to your INSTALLED_APPS
+Depending on you configuration, you may also check ``TEMPLATE_LOADERS`` and
+``TEMPLATE_DIRS`` to make sure that templates distributed within
+django-formrenderingtools are discovered.
 #######
 
 Copyright (c) 2008-2012, Benoît Bryon <benoit@marmelune.net>.
-See AUTHORS for a full list of contributors.
+See :doc:`AUTHORS` for a full list of contributors.
 
 All rights reserved.
 
 	# Freeze versions.
 	cp $(ROOT_DIR)/etc/buildout/versions-kgs.cfg $(ROOT_DIR)/etc-templates/buildout/
 	# Run zest.releaser.
-	#bin/fullrelease
+	bin/fullrelease
 django-formrenderingtools
 #########################
 
-django-formrenderingtools is an application for the `Django framework
-<http://www.djangoproject.com/>`_.
-It provides tools for the template designer to customize forms.
+Customize layout of Django forms in templates, not in Python code.
 
 Rather than using {{ form.as_p }}, set up and reuse templates to render 
 Django's form elements.
 
-For the impatient, use the bundled demo project to discover and try the
-application (see docs/demo.txt for details).
+As an example, to reproduce Django's ``{{ form.as_p }}``:
 
-This application provides a "form_layouts" template tag library
-which itself provides the following template tags:
+::
 
-* form: renders a full form, i.e. non field errors, all fields, field
-  errors, labels and help texts
-* form_errors: renders global form errors, i.e. non field errors
-* field_list: renders a set of fields in a form, with corresponding 
-  field errors, labels and help texts
-* field: renders a field, with field errors, label and help text
-* field_errors: renders errors related to a field
-* label: renders a field's label
-* help_text: renders a field's help text
+  {% load form_layouts %}
+  <form>
+    {% form layout="as_p" %}
+    <input type="submit">
+  </form>
 
-The goal of this application is to provide a pack of template tags which helps
-you render each element of a form: full form, list of fields, non field errors 
-(global errors), field errors (specific errors), field, label, help text...
 
-Every form element has a corresponding template tag, which uses templates to
-generate the output. Template designers no longer rely on developers to 
-customize the form output.
+*********
+Resources
+*********
 
-This application uses a template-naming system that lets you reuse generic 
-templates or use specific ones, depending on your needs. You can reuse built-in 
-templates, override them or create your own templates.
-
-*****
-Links
-*****
-
-HTML documentation
-  Browse the HTML documentation online at 
-  http://packages.python.org/django-formrenderingtools/
-
-RestructuredText documentation
-  Read the RestructuredText documentation in the docs/ folder in the source
-  code
-
-Source code repository
-  Follow the project on BitBucket at
-  http://bitbucket.org/benoitbryon/django-formrenderingtools
-
-Pypi
-  The project is known as "django-formrenderingtools" in the Python package
-  index. See http://pypi.python.org/pypi/django-formrenderingtools
-
-*******************
-Credits and license
-*******************
-
-This application is published under the BSD license. See 
-`docs/LICENSE.txt <http://packages.python.org/django-formrenderingtools/LICENSE.html>`_
-for details.
+* Online documentation: http://packages.python.org/django-formrenderingtools/
+* PyPI page: http://pypi.python.org/pypi/django-formrenderingtools
+* Source code repository: http://bitbucket.org/benoitbryon/django-formrenderingtools
+* Bugtracker: http://bitbucket.org/benoitbryon/django-formrenderingtools/issues

File docs/INSTALL.txt

-############
-Installation
-############
-
-The code is published under the BSD license. See :doc:`about/license` for
-details.
-
-If you just want to discover the application, you may have a look at the
-:doc:`/demo`.
-
-If you want to contribute to the code, you should go to :doc:`contribute`
-documentation.
-
-
-**********************
-Install Python package
-**********************
-
-Install the package with your favorite Python installer. As an example, with
-pip:
-
-.. code-block:: sh
-
-   pip install django-formrenderingtools
-
-
-******************************
-Update Django project settings
-******************************
-
-Add 'djc.formrenderingtools' to the INSTALLED_APPS list in your Django project
-settings.

File docs/about/AUTHORS.txt

+.. include:: ../../AUTHORS

File docs/about/CHANGELOG.txt

+.. include:: ../../CHANGELOG

File docs/about/LICENSE.txt

+.. include:: ../../LICENSE

File docs/about/alternatives.txt

 References
 **********
 
+.. target-notes::
+
 .. _`django-floppyforms`: http://pypi.python.org/pypi/django-floppyforms
 .. _`Revised form rendering project`: 
    http://www.google-melange.com/gsoc/project/google/gsoc2011/gregmuellegger/5001

File docs/about/authors.txt

-.. include:: ../../AUTHORS

File docs/about/changes.txt

-.. include:: ../../CHANGELOG

File docs/about/index.txt

 About django-formrenderingtools
 ###############################
 
-This project was initiated in 2010 in order to help web designers focus on
+This project was initiated in 2008 in order to help web designers focus on
 templates (pseudo-HTML) and CSS, whereas developers focus on Python code.
 
 .. toctree::
    :maxdepth: 1
 
    alternatives
-   license
-   authors
-   changes
+   LICENSE
+   AUTHORS
+   CHANGELOG

File docs/about/license.txt

-.. include:: ../../LICENSE

File docs/best_practices.txt

 Here are some of the guidelines about form rendering, followed in this 
 application.
 
-* Where a graphic or template designer may work, use templates rather than 
+* Where a web designer contributes to project, use templates rather than 
   Python scripts
 
 * Put CSS classes to container, so that both container and contained element

File docs/contribute.txt

 If everything went fine, you have a everything you need in the folder. Have a
 look at the provided :file:`Makefile` for details.
 
-If a proble occurred, look at the provided :file:`Makefile`. It is the live
+If a problem occurred, look at the provided :file:`Makefile`. It is the live
 install-for-development documentation.
 
 

File docs/demo.txt

 ############
 
 Django-formrenderingtools sourcecode contains a demonstration project in the
-demo/ folder.
-
-This project is a demo for the django-formrenderingtools package. Use it to
-quickly see, understand and experiment Django-formrenderingtools concepts.
+:file:`demo/` folder.
 
 The demo produces a presentation of django-formrenderingtools usage with
 examples.
 
+
+*******
 Install
-=======
+*******
 
-Check requirements. This demo requires the following software to be installed
-on your system:
+.. code-block:: sh
 
-* Python >= 2.6 ("with" statement in setup.py)
-* Virtualenv
-* Mercurial (if unavailable, download and extract the source from bitbucket
-  manually)
+  # Get the source.
+  hg clone http://bitbucket.org/benoitbryon/django-formrenderingtools
+  cd django-formrenderingtools/
+  # Install.
+  make develop
+  # You can run the server!
+  bin/django runserver
 
-With buildout
--------------
+If everything went fine, you have a everything you need in the folder. Have a
+look at the provided :file:`Makefile` for details.
 
-.. code-block:: bash
+If a problem occurred, look at the provided :file:`Makefile`. It is the live
+install-for-demo documentation.
 
-  # Get the source
-  hg clone http://bitbucket.org/benoitbryon/django-formrenderingtools
-  # Optional but recommended: create a virtual environment
-  virtualenv --distribute --no-site-packages django-formrenderingtools
-  source django-formrenderingtools/bin/activate
-  # Installation with buildout
-  cd django-formrenderingtools
-  bin/python bootstrap.py -d
-  bin/buildout
-  # You can run the tests!
-  bin/test
 
-If everything went fine, you have a buildout environment and can test the 
-application.
+****************
+Look at the demo
+****************
 
-With Virtualenv and pip
------------------------
+* Run Django's development server:
 
-.. code-block:: bash
-
-  # Clone Django-formrenderingtools (or download and extract it):
-  hg clone http://bitbucket.org/benoitbryon/django-formrenderingtools
-  # Create a virtual environment and activate it:
-  virtualenv --no-site-packages --distribute django-formrenderingtools
-  source django-formrenderingtools/bin/activate
-  # Installation with pip
-  cd django-formrenderingtools
-  bin/pip install -r requirements.txt
-  # You can run the tests!
-  bin/python demo/manage.py test formrenderingtools
-
-Look at the demo
-================
-
-* Activate the virtual environment if necessary
-* Run the development server (buildout installation):
-  ::
+  .. code-block:: sh
 
     bin/django runserver
 
-  Or (virtualenv/pip installation):
-  ::
-  
-    bin/python demo/manage.py runserver
+* Open http://localhost:8000/ in your browser.
+* Read the sourcecode in the :file:`demo/` folder of your
+  django-formrenderingtools installation.
 
-* Open http://localhost:8000/ in your browser.
-* Read the sourcecode in the demo/ folder of your django-formrenderingtools
-  installation.
 
+**********
 Experiment
-==========
+**********
 
-Use this demo project as a sandbox!
+Use the demo project as a sandbox!
 
-Demo is part of the development process
-=======================================
 
-The demo project is part of the documentation. It has been created to help
-developers discover the application. It explains real-world usage.
+.. note::
 
-The demo project is also intended to become part of the tests.
+   Demo is part of the development process and part of the documentation. It
+   has been created to both help users discover the application and developers
+   to test features with real-world use cases.

File docs/index.txt

 .. django-formrenderingtools documentation master file, created by
    sphinx-quickstart on Sat Apr 24 20:02:32 2010.
 
-#########################################
-django-formrenderingtools's documentation
-#########################################
+#########################
+django-formrenderingtools
+#########################
 
-Customize layout of forms in templates, not in Python code.
-
-``django-formrenderingtools`` is an application for the `Django framework
-<http://www.djangoproject.com/>`_. It provides tools to customize form
-rendering with templates.
+Customize layout of `Django forms`_ in templates, not in Python code.
 
 Rather than using {{ form.as_p }} and Python code, set up and reuse templates
 to render Django's form elements.
 .. code-block:: django
 
   {% load form_layouts %}
-
   <form>
     {% form layout="as_p" %}
     <input type="submit">
 
 .. note::
 
-   Notice that Django-formrenderingtools is not intended to customize widgets.
+   Django-formrenderingtools is not intended to customize widgets.
    Have a look at `django-floppyforms
    <http://pypi.python.org/pypi/django-floppyforms>`_ for this purpose.
 
    :maxdepth: 2
 
    overview
-   INSTALL
+   install
    demo
    reference/index
    migrate
    about/index
 
 
-*****
-Links
-*****
+*********
+Resources
+*********
 
-HTML documentation
-  `Browse the HTML documentation online
-  <http://packages.python.org/django-formrenderingtools/>`_.
-
-RestructuredText documentation
-  `Read the RestructuredText documentation in the docs/ folder in the source
-  code
-  <http://bitbucket.org/benoitbryon/django-formrenderingtools/src/tip/docs/>`_.
-
-Source code repository
-  `Follow the project on BitBucket
-  <http://bitbucket.org/benoitbryon/django-formrenderingtools>`_.
-
-Pypi
-  The project is known as `django-formrenderingtools
-  <http://pypi.python.org/pypi/django-formrenderingtools>`_
-  in the Python package index.
+* `Online documentation`_
+* `PyPI page`_
+* `Source code repository`_
+* `Bugtracker`_
 
 
 *******************
 Credits and license
 *******************
 
-This application is published under the BSD license. See :doc:`about/license`
-and :doc:`about/authors` for details.
+This application is published under the BSD license. See :doc:`about/LICENSE`
+and :doc:`about/AUTHORS` for details.
+
+
+.. _`Django forms`:
+   https://docs.djangoproject.com/en/1.4/topics/forms/#customizing-the-form-template
+.. _`Online documentation`:
+   http://packages.python.org/django-formrenderingtools/
+.. _`PyPI page`: http://pypi.python.org/pypi/django-formrenderingtools
+.. _`Source code repository`:
+   http://bitbucket.org/benoitbryon/django-formrenderingtools
+.. _`Bugtracker`:
+   http://bitbucket.org/benoitbryon/django-formrenderingtools/issues

File docs/install.txt

+.. include:: ../INSTALL

File docs/migrate.txt

-#######################################################
-Migrate from Django's builtins to djc.formrenderingtool
-#######################################################
+###########################################################
+Migrate from Django's builtins to django-formrenderingtools
+###########################################################
 
-django-formrenderingtools and it fits your needs? How to safely migrate 
-an existing project from standard Django's practices to formrenderingtools? 
-Here are some guidelines.
+How to safely migrate an existing project from standard Django's practices to
+django-formrenderingtools? Here are some guidelines.
+
+
+*********************************
+Install django-formrenderingtools
+*********************************
+
+See :doc:`install` for details.
+
 
 **************************************************
 Replace {{ form }} by {% form %} in your templates
 **************************************************
 
-In the templates you edit (i.e. you should not patch Django code or code of 
-any third-party application), feel free to replace any:
+In the templates you edit, feel free to replace any:
 
-* {{ form }} by {% form layout="as_table" %}
-* {{ form.as_p }} by {% form layout="as_p" %}
-* {{ form.as_ul }} by {% form layout="as_ul" %}
-* {{ form.as_table }} by {% form layout="as_table" %}
+* ``{{ form }}`` by ``{% form layout="as_table" %}``
+* ``{{ form.as_p }}`` by ``{% form layout="as_p" %}``
+* ``{{ form.as_ul }}`` by ``{% form layout="as_ul" %}``
+* ``{{ form.as_table }}`` by ``{% form layout="as_table" %}``
 
-************
-Experimental
-************
+.. note::
 
-Use Form subclass which overrides default rendering methods
-===========================================================
+   django-formrenderingtools' builtin "as_*" layouts reproduce Django's
+   behavior. Tests are written to check this fact.
 
-Such a class is not yet included in django-formrenderingtools. The idea is to 
-instantiate forms which inherit from "SomeFormRenderingToolsCompatibleForm" 
-base class which overrides default Form.__unicode__(), Form.as_table(), 
-Form.as_p() and Form.as_ul().
 
-This could be useful in some cases where:
+***********************************
+Migrate custom layouts and includes
+***********************************
 
-* you control the Form class, but not the templates (you pass a Form instance
-  to a third-party application.
-* your application defines specific form class which is used by other modules.
+Search for any ``{{ form.* }}`` occurrence in templates. You should be able to
+replace these occurrence with some django-formrenderingtools features.
 
-The main drawback is that you need to edit Python code to perform template-
-related changes.
+If you already used snippets via ``{% include %}``, you should consider
+migrating the templates to django-formrenderingtools (see
+:doc:`reference/template_names`):
+
+* it proposes a convention of directory structure;
+* if new features (such as template loading optimizations) are released, you'll
+  automatically get them.