Update docs around version discovery (#602)

docs/configuration.rst

@@ -43,7 +43,7 @@ Top level keys
 ``version``
  The version of your project.
 
- Python projects that provide the ``package`` key can have the version to be automatically determined from a ``__version__`` variable in the package's module.
+ Python projects that provide the ``package`` key, if left empty then the version will be automatically determined from the installed package's version metadata or a ``__version__`` variable in the package's module.
 
  If not provided or able to be determined, the version must be passed explicitly by the command line argument ``--version``.
 

docs/tutorial.rst

@@ -48,19 +48,27 @@ Create this folder::
 The ``.gitignore`` will remain and keep Git from not tracking the directory.
 
 
-Detecting Dates & Versions
---------------------------
+Detecting Version
+-----------------
 
-``towncrier`` needs to know what version your project is, and there are two ways you can give it:
+``towncrier`` needs to know what version your project is when generating news files.
+These are the ways you can provide it, in order of precedence (with the first taking precedence over the second, and so on):
 
-- For Python 2/3-compatible projects, a ``__version__`` in the top level package.
- This can be either a string literal, a tuple, or an `Incremental <https://github.com/twisted/incremental>`_ version.
-- Manually passing ``--version=<myversionhere>`` when interacting with ``towncrier``.
+1. Manually pass ``--version=<myversionhere>`` when interacting with ``towncrier``.
+2. Set a value for the ``version`` option in your configuration file.
+3. For Python projects with a ``package`` key in the configuration file:
 
-As an example, if your package doesn't have a ``__version__``, you can manually specify it when calling ``towncrier`` on the command line with the ``--version`` flag::
+ - install the package to use its metadata version information
+ - add a ``__version__`` in the top level package that is either a string literal, a tuple, or an `Incremental <https://github.com/twisted/incremental>`_ version
+
+As an example, you can manually specify the version when calling ``towncrier`` on the command line with the ``--version`` flag::
 
  $ towncrier build --version=1.2.3post4
 
+
+Setting Date
+------------
+
 ``towncrier`` will also include the current date (in ``YYYY-MM-DD`` format) when generating news files.
 You can change this with the ``--date`` flag::
 

src/towncrier/newsfragments/432.doc.rst

@@ -0,0 +1 @@
+Clarify version discovery behavior.

src/towncrier/newsfragments/602.doc.rst

@@ -0,0 +1 @@
+Clarify version discovery behavior.