Improve documentation

- The README is now a standalone document, also included as an
  "introduction" page;
- A new "guide" section provides more details on most features;
- A couple of typos were fixed.

The main goal was to make the README file perfectly suitable for
rendering on PyPI, while keeping its content available on the standard
documentation on ReadTheDocs.

1 files changed, 68 insertions, 137 deletions

diff --git a/README.rst b/README.rst
index 03d1691..4735cce 100644
--- a/README.rst
+++ b/README.rst
@@ -1,5 +1,5 @@
-python-semanticversion
-======================
+Introduction
+============
 
 This small python library provides a few tools to handle `SemVer`_ in Python.
 It follows strictly the 2.0.0 version of the SemVer scheme.
@@ -57,20 +57,18 @@ Import it in your code:
     import semantic_version
 
 
-.. currentmodule:: semantic_version
-
 This module provides classes to handle semantic versions:
 
-- :class:`Version` represents a version number (``0.1.1-alpha+build.2012-05-15``)
-- :class:`BaseSpec`-derived classes represent requirement specifications (``>=0.1.1,<0.3.0``):
+- ``Version`` represents a version number (``0.1.1-alpha+build.2012-05-15``)
+- ``BaseSpec``-derived classes represent requirement specifications (``>=0.1.1,<0.3.0``):
 
-  - :class:`SimpleSpec` describes a natural description syntax
-  - :class:`NpmSpec` is used for NPM-style range descriptions.
+  - ``SimpleSpec`` describes a natural description syntax
+  - ``NpmSpec`` is used for NPM-style range descriptions.
 
 Versions
 --------
 
-Defining a :class:`Version` is quite simple:
+Defining a ``Version`` is quite simple:
 
 
 .. code-block:: pycon
@@ -90,7 +88,7 @@ Defining a :class:`Version` is quite simple:
     >>> list(v)
     [0, 1, 1, [], []]
 
-If the provided version string is invalid, a :exc:`ValueError` will be raised:
+If the provided version string is invalid, a ``ValueError`` will be raised:
 
 .. code-block:: pycon
 
@@ -104,7 +102,39 @@ If the provided version string is invalid, a :exc:`ValueError` will be raised:
     ValueError: Invalid version string: '0.1'
 
 
-Obviously, :class:`Versions <Version>` can be compared:
+One may also create a ``Version`` with named components:
+
+.. code-block:: pycon
+
+    >>> semantic_version.Version(major=0, minor=1, patch=2)
+    Version('0.1.2')
+
+In that case, ``major``, ``minor`` and ``patch`` are mandatory, and must be integers.
+``prerelease`` and ``build``, if provided, must be tuples of strings:
+
+.. code-block:: pycon
+
+    >>> semantic_version.Version(major=0, minor=1, patch=2, prerelease=('alpha', '2'))
+    Version('0.1.2-alpha.2')
+
+
+Some user-supplied input might not match the semantic version scheme.
+For such cases, the ``Version.coerce`` method will try to convert any
+version-like string into a valid semver version:
+
+.. code-block:: pycon
+
+    >>> Version.coerce('0')
+    Version('0.0.0')
+    >>> Version.coerce('0.1.2.3.4')
+    Version('0.1.2+3.4')
+    >>> Version.coerce('0.1.2a3')
+    Version('0.1.2-a3')
+
+Working with versions
+"""""""""""""""""""""
+
+Obviously, versions can be compared:
 
 
 .. code-block:: pycon
@@ -133,38 +163,31 @@ You can also get a new version that represents a bump in one of the version leve
     >>> str(new_v)
     '1.1.2'
 
-It is also possible to check whether a given string is a proper semantic version string:
-
-
-.. code-block:: pycon
-
-    >>> semantic_version.validate('0.1.3')
-    True
-    >>> semantic_version.validate('0a2')
-    False
 
 
-Finally, one may create a :class:`Version` with named components instead:
-
-.. code-block:: pycon
-
-    >>> semantic_version.Version(major=0, minor=1, patch=2)
-    Version('0.1.2')
-
-In that case, ``major``, ``minor`` and ``patch`` are mandatory, and must be integers.
-``prerelease`` and ``build``, if provided, must be tuples of strings:
+Requirement specification
+-------------------------
 
-.. code-block:: pycon
+python-semanticversion provides a couple of ways to describe a range of accepted
+versions:
 
-    >>> semantic_version.Version(major=0, minor=1, patch=2, prerelease=('alpha', '2'))
-    Version('0.1.2-alpha.2')
+- The ``SimpleSpec`` class provides a simple, easily understood scheme --
+  somewhat inspired from PyPI range notations;
+- The ``NpmSpec`` class supports the whole NPM range specification scheme:
 
+  .. code-block:: pycon
 
-Requirement specification
--------------------------
+      >>> Version('0.1.2') in NpmSpec('0.1.0-alpha.2 .. 0.2.4')
+      True
+      >>> Version('0.1.2') in NpmSpec('>=0.1.1 <0.1.3 || 2.x')
+      True
+      >>> Version('2.3.4') in NpmSpec('>=0.1.1 <0.1.3 || 2.x')
+      True
 
-The :class:`SimpleSpec` object describes a range of accepted versions:
+The ``SimpleSpec`` scheme
+"""""""""""""""""""""""""
 
+Basic usage is simply a comparator and a base version:
 
 .. code-block:: pycon
 
@@ -176,6 +199,12 @@ The :class:`SimpleSpec` object describes a range of accepted versions:
     >>> s.match(Version('0.1.0'))
     False
 
+Combining specifications can be expressed as follows:
+
+  .. code-block:: pycon
+
+      >>> SimpleSpec('>=0.1.1,<0.3.0')
+
 Simpler test syntax is also available using the ``in`` keyword:
 
 .. code-block:: pycon
@@ -189,17 +218,16 @@ Simpler test syntax is also available using the ``in`` keyword:
     False
 
 
-Combining specifications can be expressed as follows:
-
-  .. code-block:: pycon
+Refer to the full documentation at
+https://python-semanticversion.readthedocs.io/en/latest/ for more details on the
+``SimpleSpec`` scheme.
 
-      >>> SimpleSpec('>=0.1.1,<0.3.0')
 
 
 Using a specification
 """""""""""""""""""""
 
-The :func:`SimpleSpec.filter` method filters an iterable of :class:`Version`:
+The ``SimpleSpec.filter`` method filters an iterable of ``Version``:
 
 .. code-block:: pycon
 
@@ -222,82 +250,6 @@ It is also possible to select the 'best' version from such iterables:
     Version('0.3.0')
 
 
-Coercing an arbitrary version string
-""""""""""""""""""""""""""""""""""""
-
-Some user-supplied input might not match the semantic version scheme.
-For such cases, the :meth:`Version.coerce` method will try to convert any
-version-like string into a valid semver version:
-
-.. code-block:: pycon
-
-    >>> Version.coerce('0')
-    Version('0.0.0')
-    >>> Version.coerce('0.1.2.3.4')
-    Version('0.1.2+3.4')
-    >>> Version.coerce('0.1.2a3')
-    Version('0.1.2-a3')
-
-
-Including pre-release identifiers in specifications
-"""""""""""""""""""""""""""""""""""""""""""""""""""
-
-When testing a :class:`Version` against a :class:`SimpleSpec`, comparisons are
-adjusted for common user expectations; thus, a pre-release version (``1.0.0-alpha``)
-will not satisfy the ``==1.0.0`` :class:`SimpleSpec`.
-
-Pre-release identifiers will only be compared if included in the :class:`BaseSpec`
-definition or (for the empty pre-release number) if a single dash is appended
-(``1.0.0-``):
-
-
-.. code-block:: pycon
-
-    >>> Version('0.1.0-alpha') in SimpleSpec('<0.1.0')  # No pre-release identifier
-    False
-    >>> Version('0.1.0-alpha') in SimpleSpec('<0.1.0-')  # Include pre-release in checks
-    True
-
-
-Including build metadata in specifications
-""""""""""""""""""""""""""""""""""""""""""
-
-Build metadata has no ordering; thus, the only meaningful comparison including
-build metadata is equality.
-
-
-.. code-block:: pycon
-
-    >>> Version('1.0.0+build2') in SimpleSpec('<=1.0.0')   # Build metadata ignored
-    True
-    >>> Version('1.0.0+build1') in SimpleSpec('==1.0.0+build2')  # Include build in checks
-    False
-
-
-NPM-based ranges
-----------------
-
-The :class:`NpmSpec` class handles NPM-style ranges:
-
-.. code-block:: pycon
-
-    >>> Version('1.2.3') in NpmSpec('1.2.2 - 1.4')
-    True
-    >>> Version('1.2.3') in NpmSpec('<1.x || >=1.2.3')
-    True
-
-Refer to https://docs.npmjs.com/misc/semver.html for a detailed description of NPM
-range syntax.
-
-
-Using with Django
-=================
-
-The :mod:`semantic_version.django_fields` module provides django fields to
-store :class:`Version` or :class:`BaseSpec` objects.
-
-More documentation is available in the :doc:`django` section.
-
 
 Contributing
 ============
@@ -323,26 +275,5 @@ When submitting patches or pull requests, you should respect the following rules
           # -*- encoding: utf-8 -*-
           # Copyright (c) The python-semanticversion project
 
-
-Contents
-========
-
-.. toctree::
-   :maxdepth: 2
-
-   reference
-   django
-   changelog
-   credits
-
-
 .. _SemVer: http://semver.org/
 .. _PyPI: http://pypi.python.org/
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-