Streamline documentation.

zopefoundation · Nov 24, 2017 · 387dc0f · 387dc0f
1 parent 5d2dff0
commit 387dc0f
Show file tree

Hide file tree

Showing 31 changed files with 153 additions and 153 deletions.
diff --git a/docs/advanced/index.rst b/docs/advanced/index.rst
@@ -5,8 +5,8 @@ Advanced users
    :numbered:
    :maxdepth: 1
 
-   Validators - Validators are used to validate converted form data. This document provides a comprehensive overview of the API and how to use it effectively. <validator>
-   Widgets - Explains in detail the design goals surrounding widgets and widget managers and how they were realized with the implemented API. <widget>
-   Content Providers - Explains how to mix content providers in forms to render more html around widgets. <contentprovider>
-   Action Managers - Explains in detail the design goals surrounding action managers and actions. The execution of actions using action handlers is also covered. The document demonstrates how actions can be created without the use of buttons. <action>
-   Browser support - This file contains a checklist, ensuring that all fields have a widget. <browser-readme>
+   Validators - Used to validate converted form data <validator>
+   Widgets and widget managers <widget>
+   Content Providers - How to mix content providers in forms to render more html around widgets. <contentprovider>
+   Actions, Action Managers and Action Handlers <action>
+   Browser support - Checklist, ensuring that all fields have a widget <browser-readme>
diff --git a/docs/informative/index.rst b/docs/informative/index.rst
@@ -5,11 +5,11 @@ Informative
    :numbered:
    :maxdepth: 1
 
-   Attribute Value Adapters - The concept of attribute value adapters is introduced and fully explained. Some motivation for this new and powerful pattern is given as well. <value>
-   Data Managers - Data managers are resposnsible for accessing and writing the data. While attribute access is the most common case, data managers can also manage other data structures, such as dictionaries. <datamanager>
-   Data Converter - Data converters convert data between internal and widget values and vice versa. <converter>
-   Terms - Terms are wrappers around sources and vocabularies to provide a common interface for choices in this package. <term>
-   Utility Functions and Classes - The ``util`` module provides several helper functions and classes. The components not tested otherwise are explained in this file. <util>
-   Add Forms for ``IAdding`` - This module provides a base class for add forms that work with the ``IAdding`` interface. <adding>
-   Testing support - The ``testing`` module provides helper functions that make it easier to test form-based code in unit tests. It also provides components that simplify testing in testbrowser and Selenium. <testing>
-   ObjectWidget caveat - Explains the current problems of ObjectWidget. <object-caveat>
+   value
+   Data Managers - Accessing and writing the data on attributes and in dictionaries <datamanager>
+   converter
+   Terms - Wrappers around sources and vocabularies providing a common interface for choices <term>
+   util
+   adding
+   testing
+   Current problems of ObjectWidget <object-caveat>
diff --git a/docs/mustread/index.rst b/docs/mustread/index.rst
@@ -5,9 +5,9 @@ Must read
    :numbered:
    :maxdepth: 1
 
-   Forms - Describes the setup and usage of forms in the most common usages. Some details are provided to the structure of form components. <forms>
-   Group Forms - This document describes how widget groups are implemented within this package and how they can be used. <group>
-   Sub-Forms - Introduces the complexities surrounding sub-forms and details two classes of sub-forms, including code examples. <subform>
-   Field Managers - Provides a comprehensive explanation of the field manager API and how it is to be used. <field>
-   Buttons - Provides a comprehensive explanation of the button manager API. It also outlines how to create buttons within schemas and how buttons are converted to actions. <button>
-   Directives - Explains the ZCML directives defines by this package, which are designed to make it easier to register new templates without writing Python code. <zcml>
+   Forms - Setup and usage of forms including structure of form components <forms>
+   Group Forms - Implementation and usage of widget groups <group>
+   Sub-Forms - Introduction into sub-forms and the implemented two classes of thereof <subform>
+   field
+   Buttons - Button manager API, creation of buttons within schemas and conversion to actions <button>
+   ZCML Directives - Register new templates without writing Python code <zcml>
diff --git a/docs/widgets/index.rst b/docs/widgets/index.rst
@@ -1,33 +1,24 @@
 Widgets
 =======
 
-Each field name documentation file comprehensively explains the widget and
+Each documentation file comprehensively explains the widget and
 how it is ensured to work properly.
 
 .. toctree::
    :maxdepth: 1
 
-   button
    checkbox
-   file-testing
-   file
-   image
-   multi
-   multi_dict_integration
-   multi_list_integration
-   object
-   object_multi_dict_integration
-   object_multi_integration
-   object_multi_list_integration
-   object_single_integration
-   objectmulti
-   orderedselect
-   password
    radio
-   select-missing-terms
-   select-source
-   select
-   submit
    text
    textarea
    textlines
+   password
+   select-index
+   orderedselect
+   file
+   file-testing
+   image
+   multi-index
+   object-index
+   button
+   submit
diff --git a/docs/widgets/multi-index.rst b/docs/widgets/multi-index.rst
@@ -0,0 +1,11 @@
+Multi Widget
+------------
+
+The multi widget allows you to add and edit one or more values.
+
+.. toctree::
+   :maxdepth: 1
+
+   Overview <multi>
+   Dict integration <multi_dict_integration>
+   List integration <multi_list_integration>
diff --git a/docs/widgets/object-index.rst b/docs/widgets/object-index.rst
@@ -0,0 +1,14 @@
+Object Widget
+-------------
+
+The `ObjectWidget` widget is about rendering a schema's fields as a single
+widget.
+
+.. toctree::
+   :maxdepth: 1
+
+   Overview <object>
+   Integration with single (non-multi) widgets <object_single_integration>
+   Integration with MultiWidget (Overview) <objectmulti>
+   Integration with MultiWidget of dict <object_multi_dict_integration>
+   Integration with MultiWidget of list <object_multi_list_integration>
diff --git a/docs/widgets/select-index.rst b/docs/widgets/select-index.rst
@@ -0,0 +1,12 @@
+Select Widget
+-------------
+
+The select widget allows you to select one or more values from a set of given
+options.
+
+.. toctree::
+   :maxdepth: 1
+
+   Overview <select>
+   Missing Terms <select-missing-terms>
+   Using sources <select-source>
diff --git a/src/z3c/form/browser/button.rst b/src/z3c/form/browser/button.rst
@@ -1,6 +1,5 @@
-=============
 Button Widget
-=============
+-------------
 
 The button widget allows you to provide buttons whose actions are defined
 using Javascript scripts. The "button" type of the "INPUT" element is

diff --git a/src/z3c/form/browser/checkbox.rst b/src/z3c/form/browser/checkbox.rst
@@ -1,6 +1,5 @@
-==============
-CheckBoxWidget
-==============
+CheckBox Widget
+---------------
 
 Note: the checkbox widget isn't registered for a field by default. You can use
 the ``widgetFactory`` argument of a ``IField`` object if you construct fields
@@ -223,7 +222,7 @@ here. (This is mostly due to changes int he SimpleVocabulary code.)
 
 
 Single Checkbox Widget
-----------------------
+######################
 
 Instead of using the checkbox widget as an UI component to allow multiple
 selection from a list of choices, it can be also used by itself to toggle a
@@ -346,7 +345,7 @@ Check HIDDEN_MODE:
 
 
 Term with non ascii __str__
----------------------------
+###########################
 
 Check if a term which __str__ returns non ascii string does not crash the update method
 

diff --git a/src/z3c/form/browser/file-testing.rst b/src/z3c/form/browser/file-testing.rst
@@ -1,6 +1,5 @@
-===================
 File Testing Widget
-===================
+-------------------
 
 The File Testing widget is just like the file widget except it has
 another hidden field where the contents of a would be file can be

diff --git a/src/z3c/form/browser/file.rst b/src/z3c/form/browser/file.rst
@@ -1,6 +1,5 @@
-===========
 File Widget
-===========
+-----------
 
 The file widget allows you to upload a new file to the server. The "file" type
 of the "INPUT" element is described here:

diff --git a/src/z3c/form/browser/image.rst b/src/z3c/form/browser/image.rst
@@ -1,6 +1,5 @@
-=============
 Image Widget
-=============
+------------
 
 The image widget allows you to submit a form to the server by clicking on an
 image. The "image" type of the "INPUT" element is described here:

diff --git a/src/z3c/form/browser/interfaces.py b/src/z3c/form/browser/interfaces.py
@@ -11,11 +11,7 @@
 # FOR A PARTICULAR PURPOSE.
 #
 ##############################################################################
-"""Browser Widget Framework Interfaces
-
-$Id$
-"""
-__docformat__ = "reStructuredText"
+"""Browser Widget Framework Interfaces """
 import zope.interface
 import zope.schema
 
@@ -34,12 +30,12 @@ def getCSSClass(klass=None, error=None, required=None,
         """Setup given css class (klass) with error and required postfix
 
         If no klass name is given the widget.wrapper class name/names get used.
-        It is also possible if more then one (empty space separated) names 
+        It is also possible if more then one (empty space separated) names
         are given as klass argument.
 
         This method can get used from your form or widget template or widget
         layout template without to re-implement the widget itself just because
-        you a different CSS class concept. 
+        you a different CSS class concept.
 
         """
 

diff --git a/src/z3c/form/browser/multi.rst b/src/z3c/form/browser/multi.rst
@@ -1,6 +1,5 @@
-============
 Multi Widget
-============
+------------
 
 The multi widget allows you to add and edit one or more values.
 
@@ -737,7 +736,7 @@ no add button:
   <input type="hidden" name="widget.name.count" value="3" />
 
 Dictionaries
-------------
+############
 
 The multi widget also supports IDict schemas.
 
@@ -956,7 +955,7 @@ We will get an error if we try and set the same key twice
 
 
 Displaying
-----------
+##########
 
 The widget can be instantiated only using the request:
 
@@ -1117,7 +1116,7 @@ We can also use the multi widget with dictionaries
 
 
 Hidden mode
------------
+###########
 
 The widget can be instantiated only using the request:
 
@@ -1214,7 +1213,7 @@ We can also use the multi widget with dictionaries
 
 
 Label
------
+#####
 
 There is an option which allows to disable the label for the subwidgets.
 You can set the `showLabel` option to `False` which will skip rendering the
@@ -1337,9 +1336,7 @@ to set the ``showLabel``. Let's see.
 
 
 Coverage happiness
-------------------
-
-
+##################
 
   >>> field = zope.schema.List(
   ...     __name__=u'foo',

diff --git a/src/z3c/form/browser/multi_dict_integration.rst b/src/z3c/form/browser/multi_dict_integration.rst
@@ -1,6 +1,5 @@
-===================================
 MultiWidget Dict integration tests
-===================================
+----------------------------------
 
 Checking components on the highest possible level.
 
@@ -33,7 +32,7 @@ In real life the form gets instantiated and destroyed with each request.
   ...     return content
 
 Empty
-------
+#####
 
 All blank and empty values:
 
@@ -58,7 +57,7 @@ All blank and empty values:
   [Apply]
 
 Some valid default values
---------------------------
+#########################
 
   >>> obj.dictOfInt = {-101: -100, -1:1, 101:100}
   >>> obj.dictOfBool = {True: False, False: True}
@@ -159,7 +158,7 @@ Some valid default values
   [Apply]
 
 dictOfInt
-----------
+#########
 
 Set a wrong value and add a new input:
 
@@ -272,7 +271,7 @@ Let's remove some items:
 
 
 dictOfBool
------------
+##########
 
 Add a new input:
 
@@ -360,7 +359,7 @@ Let's remove some items:
 
 
 dictOfChoice
--------------
+############
 
 Add a new input:
 
@@ -446,7 +445,7 @@ Let's remove some items:
 
 
 dictOfTextLine
----------------
+##############
 
 Set a wrong value and add a new input:
 
@@ -556,7 +555,7 @@ Let's remove some items:
 
 
 dictOfDate
------------
+##########
 
 Set a wrong value and add a new input:
 
@@ -761,7 +760,7 @@ Let's fix the values
     dictOfTextLine: {'lorem ipsum': 'ipsum lorem'}>
 
 Twisting some keys
--------------------
+##################
 
 Change key values, item values must stick to the new values.