Improve date handler documentation

gramps/gen/datehandler/_datedisplay.py

@@ -82,14 +82,12 @@ class DateDisplay(object):
         _("DAY MON YEAR")
         )
     """
-    :Note:
+    .. note:: Will be overridden if a locale-specific date displayer exists.
-    Will be overridden if a locale-specific date displayer exists.
 
-    If your localized ``_display_gregorian`` / ``_display_calendar`` are overridden,
+    If your localized :meth:`~_display_calendar`/:meth:`~_display_gregorian` are 
-    you should override the whole formats list according to your own formats,
+    overridden,you should override the whole formats list according to your own
-    and you need not localize the format names here.
+    formats, and you need not localize the format names here. This ``formats``
-    this ``formats`` must agree with 
+    must agree with :meth:`~_display_calendar`/:meth:`~_display_gregorian`.
-    :meth:`~_display_calendar`/:meth:`~_display_gregorian`
     """
     del _
 

gramps/gen/datehandler/_datehandler.py

@@ -101,16 +101,16 @@ def register_datehandler(locales,parse_class,display_class):
     classes with the specified language locales.
 
     Set the parser_class and display_class ._locale attribute
-    to the corresponding GrampsLocale object.
+    to the corresponding :class:`.GrampsLocale` object.
 
-    @param locales: tuple of strings containing language codes.
+    :param locales: tuple of strings containing language codes.
-        The character encoding is not included, so the language
+                    The character encoding is not included, so the language
-        should be in the form of fr_FR, not fr_FR.utf8
+                    should be in the form of fr_FR, not fr_FR.utf8
-    @type locales: tuple
+    :type locales: tuple
-    @param parse_class: Class to be associated with parsing
+    :param parse_class: Class to be associated with parsing
-    @type parse_class: DateParse
+    :type parse_class: :class:`.DateParser`
-    @param display_class: Class to be associated with displaying
+    :param display_class: Class to be associated with displaying
-    @type display_class: DateDisplay
+    :type display_class: :class:`.DateDisplay`
     """
     for lang_str in locales:
         LANG_TO_PARSER[lang_str] = parse_class

gramps/gen/datehandler/_dateparser.py

@@ -158,18 +158,17 @@ def _build_prefix_table(month_to_int, month_variants):
 def _generate_variants(months):
     """
     Generate all month variants for passing to _build_prefix_table
-    @param months an iterable ordered collection, 
+    :param months: an iterable ordered collection, 1st item is empty, the rest
-                  1st item is empty, the rest 1..N, for a
+                   1..N, for a calendar with N months overall, contain, each,
-                  calendar with N months overall, contain, each,
+                   an iterable of alternative specifications.
-                  an iterable of alternative specifications.
+                   Each such specification can be:
-                  Each such specification can be:
+                     1) a Lexeme, supporting .variants() to return the list of
-                    1) a Lexeme, supporting .variants()
+                        variants underneath
-                    to return the list of variants underneath
+                     2) a literal string
-                    2) a literal string
+                     3) a |-separated string of alternatives
-                    3) a |-separated string of alternatives
+                   Empty strings are discarded.
-                  Empty strings are discarded.
+    :return: generator of lists per month with all variants listed once only
-    @return generator of lists per month with all variants listed once only
+             the 1st item will be empty
-            the 1st item will be empty
     """
 
     for month_lexemes_and_alternatives in months:
@@ -193,7 +192,7 @@ def _generate_variants(months):
 #-------------------------------------------------------------------------
 class DateParser(object):
     """
-    Convert a text string into a Date object. If the date cannot be
+    Convert a text string into a :class:`.Date` object. If the date cannot be
     converted, the text string is assigned.
     """
 
@@ -377,7 +376,9 @@ class DateParser(object):
         may be called first as DateParser.init_strings(self) so that the
         invariant expresions don't need to be repeteadly coded. All differences
         can be coded after DateParser.init_strings(self) call, that way they
-        override stuff from this method. See DateParserRU() as an example.
+        override stuff from this method.
+        
+        .. seealso:: :class:`.DateParserRU` as an example.
         """
         _ = self._locale.translation.gettext
         self.__init_prefix_tables()
@@ -876,7 +877,7 @@ class DateParser(object):
     
     def parse(self, text):
         """
-        Parses the text, returning a Date object.
+        Parses the text, returning a :class:`.Date` object.
         """
         new_date = Date()
         try:

gramps/gen/datehandler/_datestrings.py

@@ -40,7 +40,7 @@ log = logging.getLogger(".DateStrings")
 #-------------------------------------------------------------------------
 class DateStrings(object):
     """
-    String tables for :class:`~DateDisplay` and :class:`~DateParser`.
+    String tables for :class:`.DateDisplay` and :class:`.DateParser`.
     """
 
     # This table needs not be localized, it's only for parsing 
@@ -233,16 +233,17 @@ __doc__ += """
 __main__
 --------
 
-Run this code with the appropriate ``LANG`` and ``LC_DATE`` set for your target language,
+Run this code with the appropriate ``LANG`` and ``LC_DATE`` set for your target
-in order to generate the .po snippets initialized with the strings from your locale
+language, in order to generate the .po snippets initialized with the strings
-(from the deprecated data provided in _grampslocale).
+from your locale (from the deprecated data provided in _grampslocale).
+
+E.g., for French::
 
-E.g., for French:
-::
     LANG=fr_FR.utf8 LC_ALL=fr_FR.utf8 GRAMPS_RESOURCES=$PWD python -m gramps.gen.datehandler._datestrings
 
-Then merge the output into your language's .po file, and further modify the strings as needed.
+Then merge the output into your language's .po file, and further modify the
-Then remove the strings from your language's ``DateParserXX`` and ``DateHandlerXX`` classes.
+strings as needed. Then remove the strings from your language's
+:class:`DateParserXX` and :class:`DateHandlerXX` classes.
 """
 
 if __name__ == '__main__':

gramps/gen/datehandler/_dateutils.py

@@ -61,27 +61,27 @@ def set_format(value):
 
 def set_date(date_base, text) :
     """
-    Set the date of the DateBase instance.
+    Set the date of the :class:`.DateBase` instance.
     
-    The date is parsed into a Date instance.
+    The date is parsed into a :class:`.Date` instance.
-    
-    @param date_base: The DateBase instance to set the date to.
-    @type date_base: DateBase
-    @param text: The text to use for the text string in date
-    @type text: str
     
+    :param date_base: The :class:`.DateBase` instance to set the date to.
+    :type date_base: :class:`.DateBase`
+    :param text: The text to use for the text string in date
+    :type text: str
     """
     parser.set_date(date_base.get_date_object(), text)
 
 def get_date(date_base) :
     """
-    Return a string representation of the date of the DateBase instance.
+    Return a string representation of the date of the :class:`.DateBase`
+    instance.
     
     This representation is based off the default date display format
-    determined by the locale's DateDisplay instance.
+    determined by the locale's :class:`.DateDisplay` instance.
-    @return: Returns a string representing the DateBase date
-    @rtype: str
 
+    :return: Returns a string representing the :class:`.DateBase` date
+    :rtype: str
     """
     return displayer.display(date_base.get_date_object())