Commits

Erik Grinaker committed e0a34d0

use doctest for documentation code examples

Comments (0)

Files changed (8)

 ^build/
 ^dist/
+^doc/doctest/
 ^doc/doctrees/
 ^doc/html/
 ^MANIFEST$
   * Update NEWS file
   * ./setup.py test
   * ./setup.py test -p python3.1
+  * ./setup.py doctest
   * hg commit -m "prepare version x.y.z" && hg push
 
 * Generate the source distribution
 * Added chrono.DEFAULT_CALENDAR for setting default calendar
 * Added chrono.DEFAULT_PARSER for setting default parser
 
+Bugfixes:
+
+* Fixed some errors in the documentation code examples
+
 2010-02-06: 0.2.0
 =================
 

Empty file added.

doc/source/conf.py

 # extensions
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
 ]
 
 # document info
 pygments_style = "sphinx"
 html_theme = "default"
 html_show_sourcelink = False
+
+# doctest setup
+doctest_global_setup = """
+import chrono
+import datetime
+import time
+"""

doc/source/usage.rst

 attributes :attr:`chrono.Date.year`, :attr:`chrono.Date.month`, and
 :attr:`chrono.Date.day` will contain the respective date parts::
 
+.. doctest::
+
    >>> date = chrono.Date("2009-07-23")
    >>> date.year
    2009
 
 To retrieve all the attributes at once, use :meth:`chrono.Date.get`::
 
+.. doctest::
+
    >>> date = chrono.Date("2009-07-23")
    >>> date.get()
    (2009, 7, 23)
 The default :class:`chrono.parser.CommonParser` parser handles most normal
 date formats, such as::
 
+.. doctest::
+
    >>> # ISO dates
    >>> chrono.Date("2009-07-23").get()
    (2009, 7, 23)
 
    >>> # european dates
    >>> chrono.Date("23.07.2009").get()
+   (2009, 7, 23)
 
    >>> # ISO week dates
    >>> chrono.Date("2009-W32").get()
 In order to parse all valid date formats for a region, you can pass the
 proper parser class to :class:`chrono.Date`::
 
+.. doctest::
+
    >>> # US dates with two-digit year and no separator
    >>> chrono.Date("072309", chrono.parser.USParser).get()
    (2009, 7, 23)
 of :exc:`chrono.error.DateError` (such as :exc:`chrono.error.MonthError`)
 if the date was parsed properly but contained an invalid date value::
 
+.. doctest::
+
    >>> date = chrono.Date("xyz")
-   chrono.error.ParseError: Invalid ISO date value 'xyz'
+   Traceback (most recent call last):
+   ParseError: Invalid ISO date value 'xyz'
 
    >>> date = chrono.Date("2009-13-27")
-   chrono.error.MonthError: Month '13' not in range 1-12
+   Traceback (most recent call last):
+   MonthError: Month '13' not in range 1-12
 
 You can also pass a range of non-string inputs to the class, which will
 be handled according to the object type::
 
+.. doctest::
+
    >>> # boolean True indicates the current date
-   >>> chrono.Date(True).get()
+   >>> chrono.Date(True).get() # doctest: +SKIP
    (2010, 1, 23)
 
    >>> # integers are interpreted as UNIX timestamps
    (2010, 1, 17)
 
    >>> # fetch data from time.struct_time objects
-   >>> chrono.Date(time.localtime()).get()
+   >>> chrono.Date(time.localtime()).get() # doctest: +SKIP
    (2010, 1, 23)
 
    >>> # fetch data from datetime.date objects
 To parse date strings without instantiating a :class:`chrono.Date` object, you
 can use the parser classes directly::
 
+.. doctest::
+
    >>> # parses all supported ISO date formats
    >>> chrono.parser.ISOParser.parse_date("2009-07-23")
    (2009, 7, 23)
 :class:`chrono.Date` has a number of methods for retreiving calendar-related
 information about about a date, such as::
 
+.. doctest::
+
    >>> # week that contains the date
    >>> chrono.Date("2009-07-23").week()
    (2009, 30)
 To use the US calendar instead, pass the :class:`chrono.calendar.USCalendar`
 class to :class:`chrono.Date`::
 
+.. doctest::
+
    >>> # US week containing date
    >>> chrono.Date("2009-07-23", calendar=chrono.calendar.USCalendar).week()
    (2009, 30)
 
-   >>> US weekday of the date
+   >>> # US weekday of the date
    >>> chrono.Date("2009-07-23", calendar=chrono.calendar.USCalendar).weekday()
    5
 
 instantiate a :class:`chrono.Date` object, you can use the underlying
 calendar class directly::
 
+.. doctest::
+
    >>> chrono.calendar.ISOCalendar.yeardays(2008)
    366
 
 
 Here are some examples::
 
+.. doctest::
+
    >>> # adding days to a date
    >>> date = chrono.Date("2009-07-26")
    >>> date.day += 10
 takes a string containing substitution variables of the form ``$name`` or
 ``${name}``, and replaces them with actual values::
 
+.. doctest::
+
    >>> # full human-readable date
    >>> chrono.Date("2009-07-23").format("$weekdayname $day. $monthname $year")
    'Thursday 23. July 2009'
 Date comparisons can be done using the normal Python comparison operators: ``==``,
 ``!=``, ``>``, and ``<``::
 
+.. doctest::
+
    >>> chrono.Date("2009-07-31") == chrono.Date(year = 2009, month = 7, day = 31)
    True
 
 :class:`time.struct_time` or :class:`datetime.date` objects, and any other value that
 :class:`chrono.Date` is able to process::
 
+.. doctest::
+
    >>> # string with ISO date
    >>> chrono.Date("2009-07-31") == "2009-07-31"
    True
    False
 
    >>> # datetime.date objects
-   >>> chrono.Date("2009-07-31") < datetime.date(2009, 2, 17)
+   >>> chrono.Date("2009-07-31") >= datetime.date(2009, 2, 17)
    True
 build-dir = doc/
 fresh-env = True
 
+[doctest]
+builder = doctest
+build-dir = doc/doctest/
+fresh-env = True
+source-dir = doc/source/
+
 [sdist]
 formats = bztar,zip
 if "sdist" in sys.argv and not "build_sphinx" in sys.argv:
     sys.argv.insert(1, "build_sphinx")
 
-if "build_sphinx" in sys.argv:
+if "build_sphinx" in sys.argv or "doctest" in sys.argv:
     from sphinx.setup_command import BuildDoc
     cmdclass["build_sphinx"] = BuildDoc
+    cmdclass["doctest"] = BuildDoc
 
 
 class Test(Command):
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.