From df177b96c149f9c9b448e8972d3b9b580259917e Mon Sep 17 00:00:00 2001
From: "Amber Brown (HawkOwl)" <hawkowl@atleastfornow.net>
Date: Sun, 29 Nov 2015 23:09:05 +0800
Subject: [PATCH] more stuff :D

---
 LICENSE                     |  3 ++
 README.rst                  | 64 ++++++++++++++++++++++++++++++++++++-
 examplesetup.py             | 30 +++++++++++++++++
 setup.py                    |  2 ++
 src/exampleproj/__init__.py |  1 +
 src/exampleproj/_version.py |  4 +++
 src/incremental.py          | 16 ++++++++--
 7 files changed, 117 insertions(+), 3 deletions(-)
 create mode 100644 examplesetup.py
 create mode 100644 src/exampleproj/__init__.py
 create mode 100644 src/exampleproj/_version.py

diff --git a/LICENSE b/LICENSE
index 637dabc..bc9d47f 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,3 +1,6 @@
+Incremental
+-----------
+
 This project includes code from the Twisted Project, which is licensed as below.
 
 Copyright (c) 2001-2015
diff --git a/README.rst b/README.rst
index 81bc945..6f6a138 100644
--- a/README.rst
+++ b/README.rst
@@ -1,4 +1,66 @@
 Incremental
 ===========
 
-Incremental is a small library that versions your projects.
+Incremental is a small library that versions your Python projects.
+
+
+Quick Start
+-----------
+
+Add this to the top of your ``setup.py``, assuming your code is called ``widgetbox``:
+
+.. code::
+
+    my_project = 'widgetbox'
+
+    import os, importlib
+
+    def install_incremental():
+        import importlib
+        try:
+            importlib.import_module('incremental')
+        except ImportError:
+            import pip
+            pip.main(['install', 'incremental>=0.1.0'])
+        finally:
+            globals()['incremental'] = importlib.import_module('incremental')
+
+    install_incremental()
+
+    # PICK ONE OF:
+    # If you have a src/ dir
+    base_dir = os.path.dirname(__file__)
+    src_dir = os.path.join(base_dir, "src")
+    # If you do not
+    src_dir = os.path.dirname(__file__)
+
+    version = incremental.get_version_from_project(my_project, src_dir)
+
+And in the ``setup`` call, add:
+
+.. code::
+
+   setup(
+       name=my_project,
+       version=version.base(),
+       ...
+   }
+
+Then in your project add a ``_version.py`` that contains:
+
+.. code::
+
+   from incremental import Version
+
+   __version__ = Version("widgetbox", 1, 2, 3)
+   __all__ = ["__version__"]
+
+
+Then in your project's ``__init__.py`` add:
+
+.. code::
+
+   from ._version import __version__
+
+
+Subsequent installations of your project will use incremental for versioning.
diff --git a/examplesetup.py b/examplesetup.py
new file mode 100644
index 0000000..04d1fac
--- /dev/null
+++ b/examplesetup.py
@@ -0,0 +1,30 @@
+my_project = 'exampleproj'
+
+import os, importlib
+
+def install_incremental():
+    import importlib
+    try:
+        importlib.import_module('incremental')
+    except ImportError:
+        import pip
+        pip.main(['install', 'incremental>=15.0.0'])
+    finally:
+        globals()['incremental'] = importlib.import_module('incremental')
+
+install_incremental()
+
+# PICK ONE OF:
+# If you have a src/ dir
+base_dir = os.path.dirname(__file__)
+src_dir = os.path.join(base_dir, "src")
+version = incremental.get_version_from_project(my_project, src_dir)
+
+# Install the package
+
+from setuptools import setup
+
+setup(
+    name=my_project,
+    version=version.base()
+)
diff --git a/setup.py b/setup.py
index 5cc47ae..81e47aa 100644
--- a/setup.py
+++ b/setup.py
@@ -17,6 +17,8 @@ import incremental
 setup(
     name='incremental',
     version=incremental.__version__.base(),
+    maintainer='Amber Brown',
+    maintainer_email='hawkowl@twistedmatrix.com',
     classifiers = [
         "Intended Audience :: Developers",
         "License :: OSI Approved :: MIT License",
diff --git a/src/exampleproj/__init__.py b/src/exampleproj/__init__.py
new file mode 100644
index 0000000..8dee4bf
--- /dev/null
+++ b/src/exampleproj/__init__.py
@@ -0,0 +1 @@
+from ._version import __version__
diff --git a/src/exampleproj/_version.py b/src/exampleproj/_version.py
new file mode 100644
index 0000000..f536a08
--- /dev/null
+++ b/src/exampleproj/_version.py
@@ -0,0 +1,4 @@
+from incremental import Version
+
+__version__ = Version("exampleproj", 1, 2, 3)
+__all__ = ["__version__"]
diff --git a/src/incremental.py b/src/incremental.py
index ba6c846..1304c48 100644
--- a/src/incremental.py
+++ b/src/incremental.py
@@ -403,6 +403,18 @@ def getVersionString(version):
     return result
 
 
-__version__ = Version("incremental", 0, 1, 0)
+def get_version_from_project(project, src_dir):
+    """
+    Get a L{Version} object from a flat source directory.
+    """
+    version_file = {}
 
-__all__ = ["__version__", "Version"]
+    with open(os.path.join(src_dir, project, "_version.py")) as f:
+        exec(f.read(), version_file)
+
+    return version_file["__version__"]
+
+
+__version__ = Version("incremental", 15, 0, 0)
+
+__all__ = ["__version__", "Version", "get_version_from_project"]