diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py index 3c79ffdc..d3309f1b 100644 --- a/docs/sphinx/conf.py +++ b/docs/sphinx/conf.py @@ -25,7 +25,7 @@ sys.path.append('..') # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['sphinx.ext.todo', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.coverage', - 'availability'] #, 'rst2pdf.pdfbuilder'] + 'availability'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -47,7 +47,7 @@ master_doc = 'index' # General information about the project. project = u'wxPython (Phoenix)' -copyright = u'2011, Andrea Gavana' +copyright = u'2012, Andrea Gavana' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the diff --git a/docs/sphinx/rest_substitutions/overviews/datetime_overview.rst b/docs/sphinx/rest_substitutions/overviews/datetime_overview.rst new file mode 100644 index 00000000..2c3d3908 --- /dev/null +++ b/docs/sphinx/rest_substitutions/overviews/datetime_overview.rst @@ -0,0 +1,166 @@ +.. include:: headings.inc + + +.. _date and time: + +=========================================== +|phoenix_title| **Date and Time Overview** +=========================================== + +Introduction +------------ + +wxPython provides a set of powerful classes to work with dates and times. Some of the supported features of :ref:`DateTime` class are: + +* Wide range: the range of supported dates goes from about 4714 B.C. to some 480 million years in the future. +* Precision: not using floating point calculations anywhere ensures that the date calculations don't suffer from rounding errors. +* Many features: not only all usual calculations with dates are supported, but also more exotic week and year day calculations, + work day testing, standard astronomical functions, conversion to and from strings in either strict or free format. +* Efficiency: objects of :ref:`DateTime` are small (8 bytes) and working with them is fast. + + + +All date/time classes at a glance +--------------------------------- + +There are 3 main classes related to date and time: except :ref:`DateTime` itself which represents an absolute moment in time, +there are also two classes - :ref:`TimeSpan` and :ref:`DateSpan` - which represent the intervals of time. + + + +DateTime characteristics +------------------------ + +:ref:`DateTime` stores the time as a signed number of milliseconds since the Epoch which is fixed, by convention, to Jan 1, 1970 - however +this is not visible to the class users (in particular, dates prior to the Epoch are handled just as well (or as bad) as the dates after it). +But it does mean that the best resolution which can be achieved with this class is 1 millisecond. + +The size of :ref:`DateTime` object is 8 bytes because it is represented as a 64 bit integer. The resulting range of supported dates is +thus approximatively 580 million years, but due to the current limitations in the Gregorian calendar support, only dates from Nov 24, 4714BC +are supported (this is subject to change if there is sufficient interest in doing it). + +Finally, the internal representation is time zone independent (always in GMT) and the time zones only come into play when a date is broken +into year/month/day components. See more about timezones below (see :ref:`Time zone considerations