Added recipes to documentation. Prepared for release using wheels. Ma…

…ke use of include files for Sphinx documentation. Doctesting for Sphinx documentation. Fixed broken setup.py

MANIFEST.in

@@ -1,3 +1,3 @@
 recursive-include spans *.py
 
-include MANIFEST.in LICENSE README.rst Makefile setup.py tox.ini
+include MANIFEST.in LICENSE README.rst Makefile setup.py setup.cfg tox.ini doc/*.rst

Makefile

@@ -7,10 +7,16 @@ doc:
 	make -C doc/ html
 
 test:
+	make -C doc doctest
 	tox
 
 sdist:
 	python setup.py sdist
 	rm -rf *.egg-info
 
-.PHONY : init clean-pyc test sdist
+preview-readme:
+	python -c 'import setup; print(setup.long_desc)' > README.preview.rst
+	retext README.preview.rst
+	rm README.preview.rst
+
+.PHONY : init clean-pyc test sdist preview-readme

README.rst

@@ -7,6 +7,9 @@ are conveinent when working with intervals of any kind. Every time you've found
 yourself working with date_start and date_end, an interval may have been what
 you were actually looking for.
 
+Spans has successfully been used in production since its first release
+30th August, 2013.
+
 Here is an example on how to use ranges to determine if something happened in
 the 90s.
 

doc/conf.py

@@ -78,7 +78,10 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ["_build"]
+exclude_patterns = [
+    "_build",
+    "*.inc.rst",
+]
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -288,3 +291,8 @@
 # Autodoc settings
 autodoc_docstring_signature = True
 autodoc_member_order = "groupwise"
+
+doctest_global_setup = """
+from spans import *
+from datetime import *
+"""

doc/example_contains.inc.rst

@@ -0,0 +1,11 @@
+.. doctest::
+
+    >>> from spans import *
+    >>> from datetime import *
+    >>> the90s = daterange(date(1990, 1, 1), date(2000, 1, 1))
+    >>> date(1996, 12, 4) in the90s
+    True
+    >>> date(2000, 1, 1) in the90s
+    False
+    >>> the90s.union(daterange(date(2000, 1, 1), date(2010, 1, 1)))
+    daterange([datetime.date(1990, 1, 1),datetime.date(2010, 1, 1)))

doc/index.rst

@@ -1,8 +1,14 @@
 Welcome to Spans' documentation!
 ================================
-Spans is a pure Python implementation of PostgreSQL's range types [#]_. Range types are conveinent when working with intervals of any kind. Every time you've found yourself working with ``date_start`` and ``date_end``, an interval like Spans' range may have been what you were actually looking for.
+Spans is a pure Python implementation of PostgreSQL's range types [#]_. Range types are conveinent when working with intervals of any kind. Every time you've found yourself working with ``date_start`` and ``date_end``, an interval like Spans' range may have been what you were actually looking for. Spans also provide a more flexible way of working with ranges with the range set classes.
 
-Spans also provide a more flexible way of working with ranges with the range set classes.
+Spans has successfully been used in production since its first release
+30th August, 2013.
+
+Here is an example on how to use ranges to determine if something happened in
+the 90s.
+
+.. include:: example_contains.inc.rst
 
 .. [#] http://www.postgresql.org/docs/9.2/static/rangetypes.html
 
@@ -15,5 +21,6 @@ Introduction
    introduction
    ranges
    custom_types
+   recipes
    api
    changelog

doc/recipe_overlap.inc.rst

@@ -0,0 +1,75 @@
+Check if two employees work at the same time
+--------------------------------------------
+Spans make working with intervals of time easy. In this example we want to list all hours where `Alice` and `Bob` work at the same time. 24 hour clock is used, as well as weeks starting on Monday.
+
+.. testcode::
+
+    import re
+    from datetime import timedelta
+    from spans import timedeltarange, timedeltarangeset
+
+    alice = [
+        ["8-12", "12:30-17"], # Monday
+        ["8-12", "12:30-17"], # Tuesday
+        ["8-12", "12:30-17"], # Wednesday
+        ["8-12", "12:30-17"], # Thursday
+        ["8-12", "12:30-15"], # Friday
+        ["10-14"], # Saturday
+        [], # Sunday
+    ]
+
+    bob = [
+        ["15-21"], # Monday
+        ["15-21"], # Tuesday
+        ["15-21"], # Wednesday
+        ["15-21"], # Thursday
+        ["12-18"], # Friday
+        [], # Saturday
+        ["10-14"], # Sunday
+    ]
+
+    # Convert the data to timedeltarange
+    def str_to_timedelta_range(string):
+        # Error handling left as an excersize for the reader
+        match = re.match(
+            "^(\d{1,2}):?(\d{1,2})?-(\d{1,2}):?(\d{1,2})?$", string)
+
+        return timedeltarange(
+            timedelta(hours=int(match.group(1) or 0), minutes=int(match.group(2) or 0)),
+            timedelta(hours=int(match.group(3) or 0), minutes=int(match.group(4) or 0)))
+
+    schedule_alice = timedeltarangeset(
+        str_to_timedelta_range(span).offset(timedelta(day))
+        for day, spans in enumerate(alice)
+        for span in spans)
+
+    schedule_bob = timedeltarangeset(
+        str_to_timedelta_range(span).offset(timedelta(day))
+        for day, spans in enumerate(bob)
+        for span in spans)
+
+    # Print hours where both Alice and Bob work
+    for span in schedule_alice.intersection(schedule_bob):
+        print("%-9s %02d:%02d-%02d:%02d" % (
+            {
+                0: "Monday",
+                1: "Tuesday",
+                2: "Wednesday",
+                3: "Thursday",
+                4: "Friday",
+                5: "Saturday",
+                6: "Sunday",
+            }[span.lower.days],
+            span.lower.seconds // 3600,
+            (span.lower.seconds // 60) % 60,
+            span.upper.seconds // 3600,
+            (span.upper.seconds // 60) % 60,
+        ))
+
+.. testoutput::
+
+    Monday    15:00-17:00
+    Tuesday   15:00-17:00
+    Wednesday 15:00-17:00
+    Thursday  15:00-17:00
+    Friday    12:30-15:00

doc/recipes.rst

@@ -0,0 +1,5 @@
+Recipes
+=======
+This is a showcasing of what Spans is capable of.
+
+.. include:: recipe_overlap.inc.rst

setup.cfg

@@ -0,0 +1,2 @@
+[bdist_wheel]
+universal = 1

setup.py

@@ -77,18 +77,19 @@ def process(self, text):
 
 rst_pre_processor = RstPreProcessor()
 
-@rst_pre_processor.add_role("meth")
 @rst_pre_processor.add_role("class")
 @rst_pre_processor.add_role("attr")
+@rst_pre_processor.add_role("meth")
 def role_simplyfier(processor, role, argument, content):
-    extra = {
-        "meth": "()"
+    format = {
+        "attr": "``.{}``",
+        "meth": "``{}()``",
     }
 
     if content.startswith("~"):
-        return "``{}``".format(content[1:].split(".")[-1] + extra.get(role, ""))
+        return format.get(role, "``{}``").format(content[1:].split(".")[-1])
     else:
-        return "``{}``".format(content + extra.get(role, ""))
+        return format.get(role, "``{}``").format(content + extra.get(role, ""))
 
 @rst_pre_processor.add_block("image")
 def image_remover(processor, block, args, extra, content):
@@ -128,28 +129,31 @@ def rst_preprocess(file):
     with open("requirements.txt") as fp:
         requirements = fp.read().split("\n")
 
-setup(
-    name="Spans",
-    version=version,
-    description="Continuous set support for Python",
-    long_description=long_desc,
-    license=license,
-    author="Andreas Runfalk",
-    author_email="andreas@runfalk.se",
-    url="https://www.github.com/runfalk/spans",
-    packages=["spans"],
-    install_requires=requirements,
-    classifiers=(
-        "Development Status :: 5 - Production/Stable",
-        "Intended Audience :: Developers",
-        "License :: OSI Approved :: MIT License",
-        "Programming Language :: Python",
-        "Programming Language :: Python :: 2.7",
-        "Programming Language :: Python :: 3.3",
-        "Programming Language :: Python :: 3.4",
-        "Programming Language :: Python :: 3.5",
-        "Topic :: Utilities"
-    ),
-    zip_safe=False,
-    test_suite="spans.tests.suite"
-)
+if __name__ == "__main__":
+    setup(
+        name="Spans",
+        version=version,
+        description="Continuous set support for Python",
+        long_description=long_desc,
+        license=license,
+        author="Andreas Runfalk",
+        author_email="andreas@runfalk.se",
+        url="https://www.github.com/runfalk/spans",
+        packages=["spans"],
+        install_requires=requirements,
+        classifiers=(
+            "Development Status :: 5 - Production/Stable",
+            "Intended Audience :: Developers",
+            "License :: OSI Approved :: MIT License",
+            "Programming Language :: Python",
+            "Programming Language :: Python :: 2",
+            "Programming Language :: Python :: 3",
+            "Programming Language :: Python :: 2.7",
+            "Programming Language :: Python :: 3.3",
+            "Programming Language :: Python :: 3.4",
+            "Programming Language :: Python :: 3.5",
+            "Topic :: Utilities"
+        ),
+        zip_safe=False,
+        test_suite="spans.tests.suite"
+    )