enhance readme

1 files changed, 44 insertions, 30 deletions

diff --git a/README.rst b/README.rst
index aee8cf9..6002c1c 100644
--- a/README.rst
+++ b/README.rst
@@ -1,43 +1,56 @@
 setuptools_scm
 ===============
 
-This module is a simple setup_requires utility for use
+About
+~~~~~~
+
+:code:`setuptools_scm` is a simple setup_requires utility for use
 in mercurial and git based projects.
 
-It extracts the last Tag as well as the distance to it in commits
-from the scm, and uses these to calculate a version number.
+It uses metadata from the scm to generate the **version** of a project
+and to list the files belonging to that project
+(makes MANIFEST.in unnecessary in many cases).
+
+It falls back to PKG-INFO/.hg_archival.txt when necessary/
+
+Standard Version Generation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In the standard configurations setuptools_scm takes a look at 3 things
+
+1. latest tag
+2. the distance to this tag
+3. workdir state
 
-And it provides a file finder for both scm, so MANIFEST.in is no longer needed.
+and uses roughly the following logic to render the version
 
-By default, it will increment the last component of the version by one
-and append .dev{distance}
-in case the last component is .dev, the version will be unchanged.
+not distance and clean
+    :code:`{tag}`
+distance and clean
+    :code:`{next_version}.dev{distance}+n{revision hash}`
+not distance and not clean
+    :code:`{tag}+dYYYMMMDD`
+distance and not clean
+    :code:`{next_version}.dev{distance}+n{revision hash}.dYYYMMMDD`
 
-.. warning::
 
-    Semver advises mot to use patch numbers in initial versions,
-    (i.e. 2.0 instead of 2.0.0).
-    This will yield potential mistakes/errors
-    when tagging using the shorthand version.
-    Since the default heusterics of setuptools_scm increments
-    the last number component it is necessary
-    to add the full patch version (i.e. tag v2.0.0),
-    else the logic will increment the last number of the tag.
-    which for a 2.0 tag would be the 2.1.devX version.
+The next version is calculated by adding 1 to the last numeric component
+of the tag.
 
-    Future versions of setuptools_scm will switch to semver by default,
-    hiding the the old behaviour as configurable option
+Using Semver
+~~~~~~~~~~~~
 
+Due to the default behaviour its necessary to always include a
+patch version, else the automatic guessing will increment the wrong part
+of the semver. (i.e. tag 2.0 results in 2.1.devX instead of 2.0.1.devX)
 
-It uses various strategies to archive its task:
 
-1. try to directly ask hg/git for the tag/distance
-2. try to infer it from the `.hg_archival.txt` file
-3. try to read the exact version from the 'PKG-INFO' file
-   as generated by `setup.py sdist` (this is a nasty abuse)
+Future versions of setuptools_scm will switch to semver by default,
+hiding the the old behaviour as configurable option
 
 
-The setup.py usage is:
+Setup.py
+~~~~~~~~
 
 .. code:: python
 
@@ -49,7 +62,7 @@ The setup.py usage is:
         ...,
     )
 
-If you want to configure the way use_scm_version works
+In order to configure the way use_scm_version works
 you an provide a mapping with options instead of simple truth value.
 
 
@@ -63,7 +76,7 @@ currently supported configuration keys are:
     either a entrypoint name or a callable
 
 To use setuptools_scm in other python code
-one can use the get_version function.
+you can use the get_version function.
 
 .. code:: python
 
@@ -86,11 +99,12 @@ setuptools_scm provides 2 entrypoints for adding new scms
     a function used to parse the metadata of the current workdir
     use the name of the control directoy/file of your scm as name
 
-    the return value should be a mapping created by the
-    function setuptools_scm.version:meta
+    the return value MUST be a ScmVersion instance created by the
+    function :code:`setuptools_scm.version:meta`
 
 **setuptools_scm.files_command**
-    either a string containing a shell command that prints all scm managed files in its current working directory
+    either a string containing a shell command
+    that prints all scm managed files in its current working directory
     or a callable, that given a pathname will return
 
     also use then name of your scm control directory as name of the entrypoint