From 19b39b5dc0d4d354a90acbd3cf7c81b8d903387e Mon Sep 17 00:00:00 2001 From: Nick Hall Date: Wed, 13 Nov 2013 18:41:52 +0000 Subject: [PATCH] Improve date handler documentation --- gramps/gen/datehandler/_datedisplay.py | 12 +++++----- gramps/gen/datehandler/_datehandler.py | 18 +++++++-------- gramps/gen/datehandler/_dateparser.py | 31 +++++++++++++------------- gramps/gen/datehandler/_datestrings.py | 17 +++++++------- gramps/gen/datehandler/_dateutils.py | 24 ++++++++++---------- 5 files changed, 51 insertions(+), 51 deletions(-) diff --git a/gramps/gen/datehandler/_datedisplay.py b/gramps/gen/datehandler/_datedisplay.py index a3d84039a..695360bd1 100644 --- a/gramps/gen/datehandler/_datedisplay.py +++ b/gramps/gen/datehandler/_datedisplay.py @@ -82,14 +82,12 @@ class DateDisplay(object): _("DAY MON YEAR") ) """ - :Note: - Will be overridden if a locale-specific date displayer exists. + .. note:: Will be overridden if a locale-specific date displayer exists. - If your localized ``_display_gregorian`` / ``_display_calendar`` are overridden, - you should override the whole formats list according to your own formats, - and you need not localize the format names here. - this ``formats`` must agree with - :meth:`~_display_calendar`/:meth:`~_display_gregorian` + If your localized :meth:`~_display_calendar`/:meth:`~_display_gregorian` are + overridden,you should override the whole formats list according to your own + formats, and you need not localize the format names here. This ``formats`` + must agree with :meth:`~_display_calendar`/:meth:`~_display_gregorian`. """ del _ diff --git a/gramps/gen/datehandler/_datehandler.py b/gramps/gen/datehandler/_datehandler.py index 73a761c1e..3ecd991d3 100644 --- a/gramps/gen/datehandler/_datehandler.py +++ b/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. - The character encoding is not included, so the language - should be in the form of fr_FR, not fr_FR.utf8 - @type locales: tuple - @param parse_class: Class to be associated with parsing - @type parse_class: DateParse - @param display_class: Class to be associated with displaying - @type display_class: DateDisplay + :param locales: tuple of strings containing language codes. + The character encoding is not included, so the language + should be in the form of fr_FR, not fr_FR.utf8 + :type locales: tuple + :param parse_class: Class to be associated with parsing + :type parse_class: :class:`.DateParser` + :param display_class: Class to be associated with displaying + :type display_class: :class:`.DateDisplay` """ for lang_str in locales: LANG_TO_PARSER[lang_str] = parse_class diff --git a/gramps/gen/datehandler/_dateparser.py b/gramps/gen/datehandler/_dateparser.py index 88be0c382..a40cd06cd 100644 --- a/gramps/gen/datehandler/_dateparser.py +++ b/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, - 1st item is empty, the rest 1..N, for a - calendar with N months overall, contain, each, - an iterable of alternative specifications. - Each such specification can be: - 1) a Lexeme, supporting .variants() - to return the list of variants underneath - 2) a literal string - 3) a |-separated string of alternatives - Empty strings are discarded. - @return generator of lists per month with all variants listed once only - the 1st item will be empty + :param months: an iterable ordered collection, 1st item is empty, the rest + 1..N, for a calendar with N months overall, contain, each, + an iterable of alternative specifications. + Each such specification can be: + 1) a Lexeme, supporting .variants() to return the list of + variants underneath + 2) a literal string + 3) a |-separated string of alternatives + Empty strings are discarded. + :return: generator of lists per month with all variants listed once only + 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: diff --git a/gramps/gen/datehandler/_datestrings.py b/gramps/gen/datehandler/_datestrings.py index 2bf4324fd..fbdead2fb 100644 --- a/gramps/gen/datehandler/_datestrings.py +++ b/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, -in order to generate the .po snippets initialized with the strings from your locale -(from the deprecated data provided in _grampslocale). +Run this code with the appropriate ``LANG`` and ``LC_DATE`` set for your target +language, in order to generate the .po snippets initialized with the strings +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 remove the strings from your language's ``DateParserXX`` and ``DateHandlerXX`` classes. +Then merge the output into your language's .po file, and further modify the +strings as needed. Then remove the strings from your language's +:class:`DateParserXX` and :class:`DateHandlerXX` classes. """ if __name__ == '__main__': diff --git a/gramps/gen/datehandler/_dateutils.py b/gramps/gen/datehandler/_dateutils.py index 93b595f8f..a7ce4b39b 100644 --- a/gramps/gen/datehandler/_dateutils.py +++ b/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. - - @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 + The date is parsed into a :class:`.Date` instance. + :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. - @return: Returns a string representing the DateBase date - @rtype: str - + determined by the locale's :class:`.DateDisplay` instance. + + :return: Returns a string representing the :class:`.DateBase` date + :rtype: str """ return displayer.display(date_base.get_date_object())