Doc: improve Usage section (#143)

tomschr · scls19fr · commit ecb07365ea28 · 2019-10-01T07:34:37.000+02:00
* Change titles to using verb instead of noun * Adding version information in docs/conf.py Currently, the version of semver is imported (using from semver import __version__). To avoid importing semver, version string could be managed through bumpversion2. However, this is out of scope for this PR. * Improve entry page * 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 -> pytest * Fix #142: Improve usage documentation * Use descriptive titles (verb+ing) to better find the topic * Structure the content with (sub)sections * Try to structure the different sections with list if there are different options to make it more readable * Document other, possible unknown features * Silence flake8 with "noqa: E402"
diff --git a/docs/conf.py b/docs/conf.py
@@ -20,6 +20,7 @@
 import sys
 sys.path.insert(0, os.path.abspath('..'))
 
+from semver import __version__  # noqa: E402
 
 # -- General configuration ------------------------------------------------
 
@@ -57,9 +58,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = ''
+version = __version__
 # The full version, including alpha/beta/rc tags.
-release = ''
+release = version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/docs/development.rst b/docs/development.rst
@@ -1,5 +1,5 @@
-How to Contribute
------------------
+Contributing to semver
+======================
 
 When you make changes to the code please run the tests before pushing your
 code to your fork and opening a `pull request`_:
@@ -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`
diff --git a/docs/install.rst b/docs/install.rst
@@ -1,5 +1,5 @@
-Installation
-------------
+Installing semver
+=================
 
 For Python 2:
 
diff --git a/docs/usage.rst b/docs/usage.rst
