Fix #154: Improve Description on PyPI

README.rst

@@ -1,10 +1,81 @@
-Semver |latest-version|
-=======================
+Quickstart
+==========
 
-|build-status| |python-support| |downloads| |license| |docs|
+.. teaser-begin
 
 A Python module for `semantic versioning`_. Simplifies comparing versions.
 
+|build-status| |python-support| |downloads| |license| |docs|
+
+.. teaser-end
+
+
+The module follows the ``MAJOR.MINOR.PATCH`` style:
+
+* ``MAJOR`` version when you make incompatible API changes,
+* ``MINOR`` version when you add functionality in a backwards compatible manner, and
+* ``PATCH`` version when you make backwards compatible bug fixes.
+
+Additional labels for pre-release and build metadata are supported.
+
+To import this library, use:
+
+.. code-block:: python
+
+    >>> import semver
+
+Working with the library is quite straightforward. To turn a version string into the
+different parts, use the :func:`semver.parse` function:
+
+.. code-block:: python
+
+    >>> ver = semver.parse('1.2.3-pre.2+build.4')
+    >>> ver['major']
+    1
+    >>> ver['minor']
+    2
+    >>> ver['patch']
+    3
+    >>> ver['prerelease']
+    'pre.2'
+    >>> ver['build']
+    'build.5'
+
+To raise parts of a version, there are a couple of functions available for
+you. The :func:`semver.parse_version_info` function converts a version string
+into a :class:`semver.VersionInfo` class. The function
+:func:`semver.VersionInfo.bump_major` leaves the original object untouched, but
+returns a new :class:`semver.VersionInfo` instance with the raised major part:
+
+.. code-block:: python
+
+    >>> ver = semver.parse_version_info("3.4.5")
+    >>> ver.bump_major()
+    VersionInfo(major=4, minor=0, patch=0, prerelease=None, build=None)
+
+It is allowed to concatenate different "bump functions":
+
+.. code-block:: python
+
+    >>> ver.bump_major().bump_minor()
+    VersionInfo(major=4, minor=0, patch=1, prerelease=None, build=None)
+
+To compare two versions, semver provides the :func:`semver.compare` function.
+The return value indicates the relationship between the first and second
+version:
+
+.. code-block:: python
+
+    >>> semver.compare("1.0.0", "2.0.0")
+    -1
+    >>> semver.compare("2.0.0", "1.0.0")
+    1
+    >>> semver.compare("2.0.0", "2.0.0")
+    0
+
+
+There are other functions to discover. Read on!
+
 
 .. |latest-version| image:: https://img.shields.io/pypi/v/semver.svg
    :alt: Latest version on PyPI
@@ -25,7 +96,3 @@ A Python module for `semantic versioning`_. Simplifies comparing versions.
    :target: http://python-semver.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status
 .. _semantic versioning: http://semver.org/
-
-Documentation
--------------
-|docs|

docs/index.rst

@@ -1,52 +1,18 @@
 Semver |version| -- Semantic Versioning
 =======================================
 
-|build-status| |latest-version| |python-support| |downloads| |license|
-
-.. python-semver documentation master file, created by
-   sphinx-quickstart on Tue May  1 16:51:19 2018.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-A Python module for `semantic versioning`_. Simplifies comparing versions.
-
-The module follows the ``MAJOR.MINOR.PATCH`` style:
-
-* ``MAJOR`` version when you make incompatible API changes,
-* ``MINOR`` version when you add functionality in a backwards compatible manner, and
-* ``PATCH`` version when you make backwards compatible bug fixes.
-
-Additional labels for pre-release and build metadata are supported.
-
-
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents
 
+   readme
    install
    usage
    development
    api
 
 
-.. |latest-version| image:: https://img.shields.io/pypi/v/semver.svg
-   :alt: Latest version on PyPI
-   :target: https://pypi.python.org/pypi/semver
-.. |build-status| image:: https://travis-ci.org/k-bx/python-semver.svg?branch=master
-   :alt: Build status
-   :target: https://travis-ci.org/k-bx/python-semver
-.. |python-support| image:: https://img.shields.io/pypi/pyversions/semver.svg
-   :target: https://pypi.python.org/pypi/semver
-   :alt: Python versions
-.. |downloads| image:: https://img.shields.io/pypi/dm/semver.svg
-   :alt: Monthly downloads from PyPI
-   :target: https://pypi.python.org/pypi/semver
-.. |license| image:: https://img.shields.io/pypi/l/semver.svg
-   :alt: Software license
-   :target: https://github.com/k-bx/python-semver/blob/master/LICENSE.txt
-.. _semantic versioning: http://semver.org/
-
 
 Indices and Tables
 ==================

docs/readme.rst

@@ -0,0 +1,2 @@
+.. include:: ../README.rst
+

docs/usage.rst

@@ -235,7 +235,7 @@ If you need to convert some types into other, refer to :ref:`sec.convert.version
 
 
 Comparing Versions through an Expression
----------------------------------------
+----------------------------------------
 
 If you need a more fine-grained approach of comparing two versions,
 use the :func:`semver.match` function. It expects two arguments:

semver.py

@@ -107,6 +107,7 @@ def __init__(self, major, minor=0, patch=0, prerelease=None, build=None):
 
     @property
     def major(self):
+        """The major part of a version"""
         return self._major
 
     @major.setter
@@ -115,6 +116,7 @@ def major(self, value):
 
     @property
     def minor(self):
+        """The minor part of a version"""
         return self._minor
 
     @minor.setter
@@ -123,6 +125,7 @@ def minor(self, value):
 
     @property
     def patch(self):
+        """The patch part of a version"""
         return self._patch
 
     @patch.setter
@@ -131,6 +134,7 @@ def patch(self, value):
 
     @property
     def prerelease(self):
+        """The prerelease part of a version"""
         return self._prerelease
 
     @prerelease.setter
@@ -139,6 +143,7 @@ def prerelease(self, value):
 
     @property
     def build(self):
+        """The build part of a version"""
         return self._build
 
     @build.setter