Improve a bit Genlist documentation

This can be improved lots more, but I'm out of time :(

CODING

@@ -23,6 +23,45 @@ Style
   ...also because I found it more readable and I like it more :P -davemds-
 
 
+Documentation cheatsheet
+========================
+
+* Links:
+
+  :class:`List`        (for classes)
+  :func:`elm_list_go`  (for functions)
+  :attr:`homogeneous`  (for properties)
+  :ref:`Elm_List_Mode` (for enums)
+
+  :func:`efl.evas.Object.delete`  (for items not in current scope)
+  :func:`~efl.evas.Object.delete` (will show it short, just "delete")
+
+* Formatting:
+
+  ``ELM_LIST_SCROLL``  (for enum values, bools and None)
+
+
+* Versions:
+
+.. versionadded:: 1.15
+
+.. versionchanged:: 1.15
+    Description of the change.
+
+.. deprecated:: 1.15
+    Use the blah, blah way instead.
+
+* Notes:
+
+    .. seealso:: :py:attr:`mode`
+
+    .. note:: Some text to be noted, blah, blah, blah,
+        some more information for this note, etc.
+
+    .. warning:: Same as note, but the box will be red
+        some more information for this warning, etc.
+
+
 Design patterns
 ===============
 

doc/elementary/genlist.rst

@@ -14,8 +14,8 @@ Elementary that could have more flexible items and allow many more
 entries while still being fast and low on memory usage. At the same time
 it was also made to be able to do tree structures. But the price to pay
 is more complexity when it comes to usage. If all you want is a simple
-list with icons and a single text, use the normal
+list (not much items) with icons and a single text, use the normal
-:py:class:`~efl.elementary.list.List` object.
+:class:`List` object.
 
 Genlist has a fairly large API, mostly because it's relatively complex,
 trying to be both expansive, powerful and efficient. First we will begin
@@ -26,63 +26,45 @@ Genlist item classes - creating items
 =====================================
 
 In order to have the ability to add and delete items on the fly, genlist
-implements a class (callback) system where the application provides a
+implements the item class (callback) system where the application provides a
 structure with information about that type of item (genlist may contain
 multiple different items with different classes, states and styles).
-Genlist will call the functions in this struct (methods) when an item is
+Genlist will call the functions in this class (methods) when an item is
 "realized" (i.e., created dynamically, while the user is scrolling the
 grid). All objects will simply be deleted when no longer needed with
-:py:meth:`~efl.evas.Object.delete`. :py:class:`GenlistItemClass` contains the
+:func:`efl.evas.Object.delete`. :class:`GenlistItemClass` contains the
 following members:
 
-- ``item_style`` - This is a constant string and simply defines the name
+- ``item_style`` - This is a constant string and define the name of the default
-  of the item style. It **must** be specified and the default should be
+  item style. It **must** be provided.
-  ``"default".``
+- ``decorate_item_style`` - This is a constant string and define the name of
-- ``decorate_item_style`` - This is a constant string and simply defines
+  the style to be used in the "decorate" mode.
-  the name of the decorate mode item style. It is used to specify
+  See :attr:`GenlistItem.decorate_mode`.
-  decorate mode item style. It can be used when you call
+- ``decorate_all_item_style`` - This is a constant string and
-  :py:attr:`GenlistItem.decorate_mode`.
+  define the name of the style to be used in the "decorate all" mode.
-- ``decorate_all_item_style`` - This is a constant string and simply
+  See :attr:`Genlist.decorate_mode`.
-  defines the name of the decorate all item style. It is used to specify
+- ``text_get`` - This function will be called for every text part. Should
-  decorate all item style. It can be used to set selection, checking and
+  return the text to display. See :func:`GenlistItemClass.text_get`.
-  deletion mode. This is used when you call
+- ``content_get`` - This function will be called for every content part.
-  :py:attr:`Genlist.decorate_mode`.
+  Should return an object to display, the object will be deleted by the
-- ``func`` - A struct with pointers to functions that will be called when
-  an item is going to be actually created. All of them receive a ``data``
-  parameter that will point to the same data passed to
-  :py:meth:`GenlistItem.append_to` and related item creation functions, and an
-  ``obj`` parameter that points to the genlist object itself.
-
-The function pointers inside ``func`` are ``text_get``, ``content_get``,
-``state_get`` and ``del``. The 3 first functions also receive a ``part``
-parameter described below. A brief description of these functions follows:
-
-- ``text_get`` - The ``part`` parameter is the name string of one of the
-  existing text parts in the Edje group implementing the item's theme.
-  See :py:meth:`GenlistItemClass.text_get`.
-- ``content_get`` - The ``part`` parameter is the name string of one of the
-  existing (content) swallow parts in the Edje group implementing the
-  item's theme. It must return ``None``, when no content is desired, or
-  a valid object handle, otherwise.  The object will be deleted by the
   genlist on its deletion or when the item is "unrealized". See
-  :py:meth:`GenlistItemClass.content_get`.
+  :func:`GenlistItemClass.content_get`.
-- ``func.state_get`` - The ``part`` parameter is the name string of one of
+- ``state_get`` - This function will be called for every state part. Must
-  the state parts in the Edje group implementing the item's theme. Return
+  return ``True`` for false/off or ``True`` for true/on. Genlists will
-  ``False`` for false/off or ``True`` for true/on. Genlists will
   emit a signal to its theming Edje object with ``"elm,state,xxx,active"``
   and ``"elm"`` as "emission" and "source" arguments, respectively, when
   the state is true (the default is false), where ``xxx`` is the name of
-  the (state) part.  See :py:meth:`GenlistItemClass.state_get`.
+  the (state) part.  See :func:`GenlistItemClass.state_get`.
 - ``func.del`` - This is intended for use when genlist items are deleted,
   so any data attached to the item (e.g. its data parameter on creation)
-  can be deleted. See :py:meth:`GenlistItemClass.delete`.
+  can be deleted. See :func:`GenlistItemClass.delete`.
 
 
 Available item styles
 =====================
 
-- ``default``
+- ``default`` The default style: icon, text, end icon
-- ``default_style`` The text part is a textblock
+- ``default_style`` The text part is a textblock and can use markups
 - ``double_label`` Two different text parts
 - ``icon_top_text_bottom``
 - ``group_index``
@@ -109,11 +91,6 @@ spaces in the data fields. For the default genlist item theme, we have
 **one** text part (``elm.text``), **two** content parts
 (``elm.swallow.icon`` and ``elm.swallow.end``) and **no** state parts.
 
-A genlist item may be at one of several styles. Elementary provides one
-by default - "default", but this can be extended by system or application
-custom themes/overlays/extensions (see :py:mod:`themes<efl.elementary.theme>`)
-for more details).
-
 
 Editing and Navigating
 ======================
@@ -147,7 +124,7 @@ item. :py:meth:`GenlistItem.subitems_clear` will clear all items that are
 children of the indicated parent item.
 
 To help inspect list items you can jump to the item at the top of the list
-with :py:attr:`Genlist.first_item` which will return the item pointer, and
+with :py:attr:`Genlist.first_item` which will return the first item, and
 similarly :py:attr:`Genlist.last_item` gets the item at the end of the list.
 :py:attr:`GenlistItem.next` and :py:attr:`GenlistItem.prev` get the next
 and previous items respectively relative to the indicated item. Using

efl/elementary/genlist_widget.pxi

@@ -67,29 +67,29 @@ cdef class Genlist(Object):
     property mode:
         """The mode used for sizing items horizontally.
 
-        Default value is ELM_LIST_SCROLL. This mode means that if items are too
+        Default value is ``ELM_LIST_SCROLL``. This mode means that if items are too
         wide to fit, the scroller will scroll horizontally. Otherwise items are
         expanded to fill the width of the viewport of the scroller. If it is
-        ELM_LIST_LIMIT, items will be expanded to the viewport width and limited
+        ``ELM_LIST_LIMIT``, items will be expanded to the viewport width and limited
-        to that size. If it is ELM_LIST_COMPRESS, the item width will be fixed
+        to that size. If it is ``ELM_LIST_COMPRESS``, the item width will be fixed
         (restricted to a minimum of) to the list width when calculating its size
         in order to allow the height to be calculated based on it. This allows,
         for instance, text block to wrap lines if the Edje part is configured
         with "text.min: 0 1".
 
-        .. note:: ELM_LIST_COMPRESS will make list resize slower as it will
+        :type: :ref:`Elm_List_Mode`
+
+        .. note:: ``ELM_LIST_COMPRESS`` will make list resize slower as it will
             have to recalculate every item height again whenever the list
             width changes!
 
-        .. note:: With Homogeneous mode all items in the genlist have the same
+        .. note:: With :attr:`homogeneous` mode all items in the genlist have the same
-            width/height. With ELM_LIST_COMPRESS the genlist items have
+            width/height. With ``ELM_LIST_COMPRESS`` the genlist items have
             fast initializing. However there are no sub-objects in genlist
             which can be on-the-fly resizable (such as TEXTBLOCK), as some
             dynamic resizable objects would not be diplayed properly.
 
         """
-        # TODO: The above description had badly broken English, check that
-        #       it's correct.
         def __set__(self, mode):
             elm_genlist_mode_set(self.obj, mode)