Normalize docs to docs/ (Closes #5).

Also normalize the package layout.

Thanks @jdowner-gb & tleach for the report.

1 files changed, 546 insertions, 0 deletions

diff --git a/docs/reference.rst b/docs/reference.rst
new file mode 100644
index 0000000..5b8ca3e
--- /dev/null
+++ b/docs/reference.rst
@@ -0,0 +1,546 @@
+Reference
+=========
+
+
+.. module:: semantic_version
+
+
+Module-level functions
+----------------------
+
+.. function:: compare(v1, v2)
+
+    Compare two version strings, and return a result similar to that of :func:`cmp`::
+
+        >>> compare('0.1.1', '0.1.2')
+        -1
+        >>> compare('0.1.1', '0.1.1')
+        0
+        >>> compare('0.1.1', '0.1.1-alpha')
+        1
+
+    :param str v1: The first version to compare
+    :param str v2: The second version to compare
+    :raises: :exc:`ValueError`, if any version string is invalid
+    :rtype: ``int``, -1 / 0 / 1 as for a :func:`cmp` comparison
+
+
+
+.. function:: match(spec, version)
+
+    Check whether a version string matches a specification string::
+
+        >>> match('>=0.1.1', '0.1.2')
+        True
+        >>> match('>=0.1.1', '0.1.1-alpha')
+        False
+        >>> match('~0.1.1', '0.1.1-alpha')
+        True
+
+    :param str spec: The specification to use, as a string
+    :param str version: The version string to test against the spec
+    :raises: :exc:`ValueError`, if the ``spec`` or the ``version`` is invalid
+    :rtype: ``bool``
+
+
+.. function:: validate(version)
+
+    Check whether a version string complies with the `SemVer`_ rules.
+
+    .. code-block:: pycon
+
+        >>> semantic_version.validate('1.1.1')
+        True
+        >>> semantic_version.validate('1.2.3a4')
+        False
+
+    :param str version: The version string to validate
+    :rtype: ``bool``
+
+
+Representing a version (the Version class)
+------------------------------------------
+
+.. class:: Version(version_string[, partial=False])
+
+    Object representation of a `SemVer`_-compliant version.
+
+    Constructed from a textual version string::
+
+        >>> Version('1.1.1')
+        Version('1.1.1')
+        >>> str(Version('1.1.1'))
+        '1.1.1'
+
+
+    .. rubric:: Attributes
+
+
+    .. attribute:: partial
+
+        ``bool``, whether this is a 'partial' or a complete version number.
+        Partial version number may lack :attr:`minor` or :attr:`patch` version numbers.
+
+    .. attribute:: major
+
+        ``int``, the major version number
+
+    .. attribute:: minor
+
+        ``int``, the minor version number.
+
+        May be ``None`` for a :attr:`partial` version number in a ``<major>`` format.
+
+    .. attribute:: patch
+
+        ``int``, the patch version number.
+
+        May be ``None`` for a :attr:`partial` version number in a ``<major>`` or ``<major>.<minor>`` format.
+
+    .. attribute:: prerelease
+
+        ``tuple`` of ``strings``, the prerelease component.
+
+        It contains the various dot-separated identifiers in the prerelease component.
+
+        May be ``None`` for a :attr:`partial` version number in a ``<major>``, ``<major>.<minor>`` or ``<major>.<minor>.<patch>`` format.
+
+    .. attribute:: build
+
+        ``tuple`` of ``strings``, the build component.
+
+        It contains the various dot-separated identifiers in the build component.
+
+        May be ``None`` for a :attr:`partial` version number in a ``<major>``, ``<major>.<minor>``,
+        ``<major>.<minor>.<patch>`` or ``<major>.<minor>.<patch>-<prerelease>`` format.
+
+
+    .. rubric:: Methods
+
+
+    .. method:: __iter__(self)
+
+        Iterates over the version components (:attr:`major`, :attr:`minor`,
+        :attr:`patch`, :attr:`prerelease`, :attr:`build`)::
+
+            >>> list(Version('0.1.1'))
+            [0, 1, 1, [], []]
+
+        .. note:: This may pose some subtle bugs when iterating over a single version
+                  while expecting an iterable of versions -- similar to::
+
+                      >>> list('abc')
+                      ['a', 'b', 'c']
+                      >>> list(('abc',))
+                      ['abc']
+
+
+    .. method:: __cmp__(self, other)
+
+        Provides comparison methods with other :class:`Version` objects.
+
+        The rules are:
+
+        - For non-:attr:`partial` versions, compare using the `SemVer`_ scheme
+        - If any compared object is :attr:`partial`:
+            - Begin comparison using the `SemVer`_ scheme
+            - If a component (:attr:`minor`, :attr:`patch`, :attr:`prerelease` or :attr:`build`)
+              was absent from the :attr:`partial` :class:`Version` -- represented with :obj:`None`
+              --, consider both versions equal.
+
+            For instance, ``Version('1.0', partial=True)`` means "any version beginning in ``1.0``".
+
+            ``Version('1.0.1-alpha', partial=True)`` means "The ``1.0.1-alpha`` version or any
+            ulterior build of that same version": ``1.0.1-alpha+build3`` matches, ``1.0.1-alpha.2`` doesn't.
+
+        Examples::
+
+              >>> Version('1.0', partial=True) == Version('1.0.1')
+              True
+              >>> Version('1.0.1-rc1.1') == Version('1.0.1-rc1', partial=True)
+              False
+              >>> Version('1.0.1-rc1+build345') == Version('1.0.1-rc1')
+              False
+              >>> Version('1.0.1-rc1+build345') == Version('1.0.1-rc1', partial=True)
+              True
+
+
+    .. method:: __str__(self)
+
+        Returns the standard text representation of the version::
+
+            >>> v = Version('0.1.1-rc2+build4.4')
+            >>> v
+            Version('0.1.1-rc2+build4.4')
+            >>> str(v)
+            '0.1.1-rc2+build4.4'
+
+
+    .. method:: __hash__(self)
+
+        Provides a hash based solely on the components.
+
+        Allows using a :class:`Version` as a dictionary key.
+
+        .. note:: A fully qualified :attr:`partial` :class:`Version`
+
+                  (up to the :attr:`build` component) will hash the same as the
+                  equally qualified, non-:attr:`partial` :class:`Version`::
+
+                      >>> hash(Version('1.0.1+build4')) == hash(Version('1.0.1+build4', partial=True))
+                      True
+
+
+    .. rubric:: Class methods
+
+
+    .. classmethod:: parse(cls, version_string[, partial=False])
+
+        Parse a version string into a ``(major, minor, patch, prerelease, build)`` tuple.
+
+        :param str version_string: The version string to parse
+        :param bool partial: Whether this should be considered a :attr:`partial` version
+        :raises: :exc:`ValueError`, if the :attr:`version_string` is invalid.
+        :rtype: (major, minor, patch, prerelease, build)
+
+    .. classmethod:: coerce(cls, version_string[, partial=False])
+
+        Try to convert an arbitrary version string into a :class:`Version` instance.
+
+        Rules are:
+
+        - If no minor or patch component, and :attr:`partial` is :obj:`False`,
+          replace them with zeroes
+        - Any character outside of ``a-zA-Z0-9.+-`` is replaced with a ``-``
+        - If more than 3 dot-separated numerical components, everything from the
+          fourth component belongs to the :attr:`build` part
+        - Any extra ``+`` in the :attr:`build` part will be replaced with dots
+
+        Examples:
+
+        .. code-block:: pycon
+
+          >>> Version.coerce('02')
+          Version('2.0.0')
+          >>> Version.coerce('1.2.3.4')
+          Version('1.2.3+4')
+          >>> Version.coerce('1.2.3.4beta2')
+          Version('1.2.3+4beta2')
+          >>> Version.coerce('1.2.3.4.5_6/7+8+9+10')
+          Version('1.2.3+4.5-6-7.8.9.10')
+
+        :param str version_string: The version string to coerce
+        :param bool partial: Whether to allow generating a :attr:`partial` version
+        :raises: :exc:`ValueError`, if the :attr:`version_string` is invalid.
+        :rtype: :class:`Version`
+
+
+Version specifications (the Spec class)
+---------------------------------------
+
+
+Version specifications describe a 'range' of accepted versions:
+older than, equal, similar to, …
+
+The main issue with representing version specifications is that the usual syntax
+does not map well onto `SemVer`_ precedence rules:
+
+* A specification of ``<1.3.4`` is not expected to allow ``1.3.4-rc2``, but strict `SemVer`_ comparisons allow it ;
+* Converting the previous specification to ``<=1.3.3`` in order to avoid ``1.3.4``
+  prereleases has the issue of excluding ``1.3.3+build3`` ;
+* It may be necessary to exclude either all variations on a patch-level release
+  (``!=1.3.3``) or specifically one build-level release (``1.3.3-build.434``).
+
+
+In order to have version specification behave naturally, the rules are the following:
+
+* If no pre-release number was included in the specification, pre-release numbers
+  are ignored when deciding whether a version satisfies a specification.
+* If no build number was included in the specification, build numbers are ignored
+  when deciding whether a version satisfies a specification.
+
+This means that::
+
+    >>> Version('1.1.1-rc1') in Spec('<1.1.1')
+    False
+    >>> Version('1.1.1-rc1') in Spec('<1.1.1-rc4')
+    True
+    >>> Version('1.1.1-rc1+build4') in Spec('<=1.1.1-rc1')
+    True
+    >>> Version('1.1.1-rc1+build4') in Spec('<=1.1.1-rc1+build2')
+    False
+
+In order to force matches to *strictly* compare version numbers, these additional
+rules apply:
+
+* Setting a pre-release separator without a pre-release identifier (``<=1.1.1-``)
+  forces match to take into account pre-release version::
+
+    >>> Version('1.1.1-rc1') in Spec('<1.1.1')
+    False
+    >>> Version('1.1.1-rc1') in Spec('<1.1.1-')
+    True
+
+* Setting a build separator without a build identifier (``>1.1.1+``) forces
+  satisfaction tests to include both prerelease and build identifiers::
+
+    >>> Version('1.1.1+build2') in Spec('>1.1.1')
+    False
+    >>> Version('1.1.1+build2') in Spec('>1.1.1+')
+    True
+
+.. class:: Spec(spec_string[, spec_string[, ...]])
+
+    Stores a list of :class:`SpecItem` and matches any :class:`Version` against all
+    contained :class:`specs <SpecItem>`.
+
+    It is build from a comma-separated list of version specifications::
+
+        >>> Spec('>=1.0.0,<1.2.0,!=1.1.4')
+        <Spec: (
+            <SpecItem: >= Version('1.0.0', partial=True)>,
+            <SpecItem: < Version('1.2.0', partial=True)>,
+            <SpecItem: != Version('1.1.4', partial=True)>
+        )>
+
+    Version specifications may also be passed in separated arguments::
+
+        >>> Spec('>=1.0.0', '<1.2.0', '!=1.1.4,!=1.1.13')
+        <Spec: (
+            <SpecItem: >= Version('1.0.0', partial=True)>,
+            <SpecItem: < Version('1.2.0', partial=True)>,
+            <SpecItem: != Version('1.1.4', partial=True)>,
+            <SpecItem: != Version('1.1.13', partial=True)>,
+        )>
+
+
+    .. rubric:: Attributes
+
+
+    .. attribute:: specs
+
+        Tuple of :class:`SpecItem`, the included specifications.
+
+
+    .. rubric:: Methods
+
+
+    .. method:: match(self, version)
+
+        Test whether a given :class:`Version` matches all included :class:`SpecItem`::
+
+            >>> Spec('>=1.1.0,<1.1.2').match(Version('1.1.1'))
+            True
+
+        :param version: The version to test against the specs
+        :type version: :class:`Version`
+        :rtype: ``bool``
+
+
+    .. method:: filter(self, versions)
+
+        Extract all compatible :class:`versions <Version>` from an iterable of
+        :class:`Version` objects.
+
+        :param versions: The versions to filter
+        :type versions: iterable of :class:`Version`
+        :yield: :class:`Version`
+
+
+    .. method:: select(self, versions)
+
+        Select the highest compatible version from an iterable of :class:`Version`
+        objects.
+
+        .. sourcecode:: pycon
+
+            >>> s = Spec('>=0.1.0')
+            >>> s.select([])
+            None
+            >>> s.select([Version('0.1.0'), Version('0.1.3'), Version('0.1.1')])
+            Version('0.1.3')
+
+        :param versions: The versions to filter
+        :type versions: iterable of :class:`Version`
+        :rtype: The highest compatible :class:`Version` if at least one of the
+                given versions is compatible; :class:`None` otherwise.
+
+
+    .. method:: __contains__(self, version)
+
+        Alias of the :func:`match` method;
+        allows the use of the ``version in speclist`` syntax::
+
+            >>> Version('1.1.1-alpha') in Spec('>=1.1.0,<1.1.1')
+            True
+
+
+    .. method:: __str__(self)
+
+        Converting a :class:`Spec` returns the initial description string::
+
+            >>> str(Spec('>=0.1.1,!=0.1.2'))
+            '>=0.1.1,!=0.1.2'
+
+    .. method:: __iter__(self)
+
+        Returns an iterator over the contained specs::
+
+            >>> for spec in Spec('>=0.1.1,!=0.1.2'):
+            ...     print spec
+            >=0.1.1
+            !=0.1.2
+
+    .. method:: __hash__(self)
+
+        Provides a hash based solely on the hash of contained specs.
+
+        Allows using a :class:`Spec` as a dictionary key.
+
+
+    .. rubric:: Class methods
+
+
+    .. classmethod:: parse(self, specs_string)
+
+        Retrieve a ``(*specs)`` tuple from a string.
+
+        :param str requirement_string: The textual description of the specifications
+        :raises: :exc:`ValueError`: if the ``requirement_string`` is invalid.
+        :rtype: ``(*spec)`` tuple
+
+
+.. class:: SpecItem(spec_string)
+
+    .. note:: This class belong to the private python-semanticversion API.
+
+    Stores a version specification, defined from a string::
+
+        >>> SpecItem('>=0.1.1')
+        <SpecItem: >= Version('0.1.1', partial=True)>
+
+    This allows to test :class:`Version` objects against the :class:`SpecItem`::
+
+        >>> SpecItem('>=0.1.1').match(Version('0.1.1-rc1'))  # pre-release satisfy conditions
+        True
+        >>> Version('0.1.1+build2') in SpecItem('>=0.1.1')   # build version satisfy specifications
+        True
+        >>>
+        >>> # Use the '-' marker to include the pre-release component in checks
+        >>> SpecItem('>=0.1.1-').match(Version('0.1.1-rc1')
+        False
+        >>>
+        >>> # Use the '+' marker to include the build identifier in checks
+        >>> SpecItem('<=0.1.1-alpha+').match(Version('0.1.1-alpha+build1'))
+        False
+
+
+    .. rubric:: Attributes
+
+
+    .. attribute:: kind
+
+        One of :data:`KIND_LT`, :data:`KIND_LTE`, :data:`KIND_EQUAL`, :data:`KIND_GTE`,
+        :data:`KIND_GT` and :data:`KIND_NEQ`.
+
+    .. attribute:: spec
+
+        :class:`Version` in the :class:`SpecItem` description.
+
+        It is alway a :attr:`~Version.partial` :class:`Version`.
+
+
+    .. rubric:: Class methods
+
+
+    .. classmethod:: parse(cls, requirement_string)
+
+        Retrieve a ``(kind, version)`` tuple from a string.
+
+        :param str requirement_string: The textual description of the specification
+        :raises: :exc:`ValueError`: if the ``requirement_string`` is invalid.
+        :rtype: (``kind``, ``version``) tuple
+
+
+    .. rubric:: Methods
+
+
+    .. method:: match(self, version)
+
+        Test whether a given :class:`Version` matches this :class:`SpecItem`::
+
+            >>> SpecItem('>=0.1.1').match(Version('0.1.1-alpha'))
+            True
+            >>> SpecItem('>=0.1.1-').match(Version('0.1.1-alpha'))
+            False
+
+        :param version: The version to test against the spec
+        :type version: :class:`Version`
+        :rtype: ``bool``
+
+
+    .. method:: __str__(self)
+
+        Converting a :class:`SpecItem` to a string returns the initial description string::
+
+            >>> str(SpecItem('>=0.1.1'))
+            '>=0.1.1'
+
+
+    .. method:: __hash__(self)
+
+        Provides a hash based solely on the current kind and the specified version.
+
+        Allows using a :class:`SpecItem` as a dictionary key.
+
+
+    .. rubric:: Class attributes
+
+
+    .. data:: KIND_LT
+
+        The kind of 'Less than' specifications::
+
+            >>> Version('1.0.0-alpha') in Spec('<1.0.0')
+            False
+
+    .. data:: KIND_LTE
+
+        The kind of 'Less or equal to' specifications::
+
+            >>> Version('1.0.0-alpha1+build999') in Spec('<=1.0.0-alpha1')
+            True
+
+    .. data:: KIND_EQUAL
+
+        The kind of 'equal to' specifications::
+
+            >>> Version('1.0.0+build3.3') in Spec('==1.0.0')
+            True
+
+    .. data:: KIND_GTE
+
+        The kind of 'Greater or equal to' specifications::
+
+            >>> Version('1.0.0') in Spec('>=1.0.0')
+            True
+
+    .. data:: KIND_GT
+
+        The kind of 'Greater than' specifications::
+
+            >>> Version('1.0.0+build667') in Spec('>1.0.1')
+            False
+
+    .. data:: KIND_NEQ
+
+        The kind of 'Not equal to' specifications::
+
+            >>> Version('1.0.1') in Spec('!=1.0.1')
+            False
+
+        The kind of 'Almost equal to' specifications
+
+
+
+.. _SemVer: http://semver.org/