From 2d1150000bc51bae7208871a304ab75b137261ba Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rapha=C3=ABl=20Barrois?= <raphael.barrois@polyconseil.fr>
Date: Wed, 16 May 2012 11:03:46 +0200
Subject: More doc.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Raphaël Barrois <raphael.barrois@polyconseil.fr>
---
 doc/django.rst    |  0
 doc/index.rst     | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 doc/reference.rst |  0
 3 files changed, 59 insertions(+), 1 deletion(-)
 create mode 100644 doc/django.rst
 create mode 100644 doc/reference.rst

diff --git a/doc/django.rst b/doc/django.rst
new file mode 100644
index 0000000..e69de29
diff --git a/doc/index.rst b/doc/index.rst
index 2a797f7..fc8ba9d 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -9,9 +9,64 @@ python-semanticversion
 This small python library provides a few tools to handle `SemVer <http://semver.org>`_ in Python.
 
 
-The first release (0.1.0) should handle the 2.0.0-rc1 version of the SemVer scheme.
+The first release (1.0.0) should handle the 2.0.0-rc1 version of the SemVer scheme.
 
 
+Getting started
+===============
+
+.. currentmodule:: semantic_version
+
+This module provides two classes to handle semantic versions:
+
+- :class:`Version` represents a version number (``0.1.1-alpha+build.2012-05-15``)
+- :class:`Spec` represents a requirement specification (``>=0.1.1``)
+
+
+Defining a :class:`Version` is quite simple::
+
+    >>> import semantic_version
+    >>> v = semantic_version.Version('0.1.1')
+    >>> v.major
+    0
+    >>> v.minor
+    1
+    >>> v.patch
+    1
+    >>> v.prerelease
+    []
+    >>> v.build
+    []
+    >>> list(v)
+    [0, 1, 1, [], []]
+
+If the provided version string is invalid, a :exc:`ValueError` will be raised::
+
+    >>> semantic_version.Version('0.1')
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+      File "/Users/rbarrois/dev/semantic_version/src/semantic_version/base.py", line 64, in __init__
+        major, minor, patch, prerelease, build = self.parse(version_string, partial)
+      File "/Users/rbarrois/dev/semantic_version/src/semantic_version/base.py", line 86, in parse
+        raise ValueError('Invalid version string: %r' % version_string)
+    ValueError: Invalid version string: '0.1'
+
+In order to define "relaxed" version strings, you must pass in ``partial=True``::
+
+    >>> v = semantic_version.Version('0.1', partial=True)
+    >>> list(v)
+    [0, 1, None, None, None]
+
+
+Obviously, :class:`Versions <Version>` can be compared::
+
+    >>> semantic_version.Version('0.1.1') < semantic_version.Version('0.1.2')
+    True
+    >>> semantic_version.Version('0.1.1') > semantic_version.Version('0.1.1-alpha')
+    True
+    >>> semantic_version.Version('0.1.1') <= semantic_version.Version('0.1.1-alpha')
+    False
+
 Links
 =====
 
@@ -26,6 +81,9 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   django
+   reference
+
 
 
 Indices and tables
diff --git a/doc/reference.rst b/doc/reference.rst
new file mode 100644
index 0000000..e69de29
-- 
cgit v1.2.1