Improve entry page

tomschr · tomschr · commit 4d15b25d35a5 · 2019-09-30T14:38:21.000+02:00
* Improve main title with semver's version and a catchy phrase
* Move the |latest-version| placeholder to the other placeholders
  like build status, downloads etc.
* Remove the "Welcome bla" heading as it introduces a lonly section
  and it is mostly useless
* Add a short explanation about the "version style" major.minor.patch
  (cited from semver.org)
* Reference the other parts with just the filename (with the .rst extension)
  and without the title. The title is automatically retrieved from
  the file, no need to repeat it. This makes the overall doc more consistent.
* Change py.test -&gt; pytest
diff --git a/docs/development.rst b/docs/development.rst
@@ -8,7 +8,7 @@ code to your fork and opening a `pull request`_:
 
     python setup.py test
 
-We use `py.test`_ and `tox`_ to run tests against all supported Python
+We use `pytest`_ and `tox`_ to run tests against all supported Python
 versions.  All test dependencies are resolved automatically, apart from
 virtualenv, which for the moment you still may have to install manually:
 
@@ -24,5 +24,5 @@ You can use the ``clean`` command to remove build and test files and folders:
 
 
 .. _pull request: https://github.com/k-bx/python-semver/pulls
-.. _py.test: http://pytest.org/
+.. _pytest: http://pytest.org/
 .. _tox: http://tox.testrun.org/
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,26 +1,33 @@
-Semver |latest-version|
-=======================
+Semver |version| -- Semantic Versioning
+=======================================
 
-|build-status| |python-support| |downloads| |license|
+|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.
 
-Welcome to python-semver's documentation!
-=========================================
+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:
+   :caption: Contents
 
-   Install <install.rst>
-   Usage <usage.rst>
-   Development <development.rst>
-   API <api.rst>
-
-A Python module for `semantic versioning`_. Simplifies comparing versions.
+   install
+   usage
+   development
+   api
 
 
 .. |latest-version| image:: https://img.shields.io/pypi/v/semver.svg
@@ -41,7 +48,7 @@ A Python module for `semantic versioning`_. Simplifies comparing versions.
 .. _semantic versioning: http://semver.org/
 
 
-Indices and tables
+Indices and Tables
 ==================
 
 * :ref:`genindex`
