Support PEP-440 version spec for developers.

28 files changed, 67 insertions, 44 deletions

diff --git a/README.rst b/README.rst
index 16d796a80..391d0bd1a 100644
--- a/README.rst
+++ b/README.rst
@@ -8,10 +8,29 @@ This is the Sphinx documentation generator, see http://sphinx-doc.org/.
 Installing
 ==========
 
-Use ``setup.py``::
+Install from PyPI to use stable version::
 
-   python setup.py build
-   sudo python setup.py install
+   pip install -U sphinx
+
+Install from PyPI to use beta version::
+
+   pip install -U --pre sphinx
+
+Install from newest dev version in stable branch::
+
+   pip install git+https://github.com/sphinx-doc/sphinx@stable
+
+Install from newest dev version in master branch::
+
+   pip install git+https://github.com/sphinx-doc/sphinx
+
+Install from cloned source::
+
+   pip install .
+
+Install from cloned source as editable::
+
+   pip install -e .
 
 
 Reading the docs
diff --git a/setup.cfg b/setup.cfg
index e0ef58591..2d2f3b535 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -1,5 +1,5 @@
 [egg_info]
-tag_build = dev
+tag_build = .dev
 tag_date = true
 
 [aliases]
diff --git a/sphinx/__init__.py b/sphinx/__init__.py
index 335f7c223..1e1b5bc6f 100644
--- a/sphinx/__init__.py
+++ b/sphinx/__init__.py
@@ -16,18 +16,22 @@ import sys
 from os import path
 
 __version__  = '1.3+'
-__released__ = '1.3.1'  # used when Sphinx builds its own docs
+__released__ = '1.3+'  # used when Sphinx builds its own docs
+
 # version info for better programmatic use
 # possible values for 3rd element: 'alpha', 'beta', 'rc', 'final'
 # 'final' has 0 as the last element
-version_info = (1, 3, 1, 'final', 0)
+version_info = (1, 3, 1, 'beta', 1)
 
 package_dir = path.abspath(path.dirname(__file__))
 
-if '+' in __version__ or 'pre' in __version__:
+__display_version__ = __version__  # used for command line version
+if __version__.endswith('+'):
     # try to find out the changeset hash if checked out from hg, and append
     # it to __version__ (since we use this value from setup.py, it gets
     # automatically propagated to an installed copy as well)
+    __display_version__ = __version__
+    __version__ = __version__[:-1]  # remove '+' for PEP-440 version spec.
     try:
         import subprocess
         p = subprocess.Popen(['git', 'show', '-s', '--pretty=format:%h',
@@ -35,7 +39,7 @@ if '+' in __version__ or 'pre' in __version__:
                              stdout=subprocess.PIPE, stderr=subprocess.PIPE)
         out, err = p.communicate()
         if out:
-            __version__ += '/' + out.decode().strip()
+            __display_version__ += '/' + out.decode().strip()
     except Exception:
         pass
 
diff --git a/sphinx/apidoc.py b/sphinx/apidoc.py
index ad5b8d04a..6891aec1c 100644
--- a/sphinx/apidoc.py
+++ b/sphinx/apidoc.py
@@ -22,7 +22,7 @@ import optparse
 from os import path
 
 from sphinx.util.osutil import walk
-from sphinx import __version__
+from sphinx import __display_version__
 
 # automodule options
 if 'SPHINX_APIDOC_OPTIONS' in os.environ:
@@ -318,7 +318,7 @@ Note: By default this script will not overwrite already created files.""")
     (opts, args) = parser.parse_args(argv[1:])
 
     if opts.show_version:
-        print('Sphinx (sphinx-apidoc) %s' % __version__)
+        print('Sphinx (sphinx-apidoc) %s' % __display_version__)
         return 0
 
     if not args:
diff --git a/sphinx/application.py b/sphinx/application.py
index b87689e71..f65592b1d 100644
--- a/sphinx/application.py
+++ b/sphinx/application.py
@@ -111,7 +111,7 @@ class Sphinx(object):
         self.messagelog = deque(maxlen=10)
 
         # say hello to the world
-        self.info(bold('Running Sphinx v%s' % sphinx.__version__))
+        self.info(bold('Running Sphinx v%s' % sphinx.__display_version__))
 
         # status code for command-line application
         self.statuscode = 0
@@ -158,7 +158,7 @@ class Sphinx(object):
 
         # check the Sphinx version if requested
         if self.config.needs_sphinx and \
-           self.config.needs_sphinx > sphinx.__version__[:3]:
+           self.config.needs_sphinx > sphinx.__display_version__[:3]:
             raise VersionRequirementError(
                 'This project needs at least Sphinx v%s and therefore cannot '
                 'be built with this version.' % self.config.needs_sphinx)
@@ -453,7 +453,7 @@ class Sphinx(object):
 
     def require_sphinx(self, version):
         # check the Sphinx version if requested
-        if version > sphinx.__version__[:3]:
+        if version > sphinx.__display_version__[:3]:
             raise VersionRequirementError(version)
 
     def import_object(self, objname, source=None):
diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py
index 3a617bb67..431ac4091 100644
--- a/sphinx/builders/html.py
+++ b/sphinx/builders/html.py
@@ -26,7 +26,7 @@ from docutils.utils import new_document
 from docutils.frontend import OptionParser
 from docutils.readers.doctree import Reader as DoctreeReader
 
-from sphinx import package_dir, __version__
+from sphinx import package_dir, __display_version__
 from sphinx.util import jsonimpl, copy_static_entry
 from sphinx.util.osutil import SEP, os_path, relative_uri, ensuredir, \
     movefile, ustrftime, copyfile
@@ -343,7 +343,7 @@ class StandaloneHTMLBuilder(Builder):
             script_files = self.script_files,
             language = self.config.language,
             css_files = self.css_files,
-            sphinx_version = __version__,
+            sphinx_version = __display_version__,
             style = stylename,
             rellinks = rellinks,
             builder = self.name,
diff --git a/sphinx/cmdline.py b/sphinx/cmdline.py
index c602cceac..e5335f47d 100644
--- a/sphinx/cmdline.py
+++ b/sphinx/cmdline.py
@@ -18,7 +18,7 @@ from os import path
 from six import text_type, binary_type
 from docutils.utils import SystemMessage
 
-from sphinx import __version__
+from sphinx import __display_version__
 from sphinx.errors import SphinxError
 from sphinx.application import Sphinx
 from sphinx.util import Tee, format_exception_cut_frames, save_traceback
@@ -40,7 +40,7 @@ Filename arguments:
   without -a and without filenames, write new and changed files.
   with -a, write all files.
   with filenames, write these.
-""" % __version__
+""" % __display_version__
 
 EPILOG = """\
 For more information, visit <http://sphinx-doc.org/>.
@@ -131,7 +131,7 @@ def main(argv):
 
     # handle basic options
     if opts.version:
-        print('Sphinx (sphinx-build) %s' % __version__)
+        print('Sphinx (sphinx-build) %s' % __display_version__)
         return 0
 
     # get paths (first and second positional argument)
diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py
index 39a393fc3..bf0ad5fa9 100644
--- a/sphinx/ext/autodoc.py
+++ b/sphinx/ext/autodoc.py
@@ -1525,7 +1525,7 @@ def setup(app):
     app.add_event('autodoc-process-signature')
     app.add_event('autodoc-skip-member')
 
-    return {'version': sphinx.__version__, 'parallel_read_safe': True}
+    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
 
 
 class testcls:
diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py
index d9594638e..4fd44ac67 100644
--- a/sphinx/ext/autosummary/__init__.py
+++ b/sphinx/ext/autosummary/__init__.py
@@ -584,4 +584,4 @@ def setup(app):
     app.connect('doctree-read', process_autosummary_toc)
     app.connect('builder-inited', process_generate_options)
     app.add_config_value('autosummary_generate', [], True)
-    return {'version': sphinx.__version__, 'parallel_read_safe': True}
+    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
diff --git a/sphinx/ext/coverage.py b/sphinx/ext/coverage.py
index 1e455a6f4..8e3ac1ae3 100644
--- a/sphinx/ext/coverage.py
+++ b/sphinx/ext/coverage.py
@@ -266,4 +266,4 @@ def setup(app):
     app.add_config_value('coverage_ignore_c_items', {}, False)
     app.add_config_value('coverage_write_headline', True, False)
     app.add_config_value('coverage_skip_undoc_in_source', False, False)
-    return {'version': sphinx.__version__, 'parallel_read_safe': True}
+    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
diff --git a/sphinx/ext/doctest.py b/sphinx/ext/doctest.py
index a05f489c6..fda4ea83b 100644
--- a/sphinx/ext/doctest.py
+++ b/sphinx/ext/doctest.py
@@ -444,4 +444,4 @@ def setup(app):
     app.add_config_value('doctest_test_doctest_blocks', 'default', False)
     app.add_config_value('doctest_global_setup', '', False)
     app.add_config_value('doctest_global_cleanup', '', False)
-    return {'version': sphinx.__version__, 'parallel_read_safe': True}
+    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
diff --git a/sphinx/ext/extlinks.py b/sphinx/ext/extlinks.py
index c9a3f3641..1f93fc944 100644
--- a/sphinx/ext/extlinks.py
+++ b/sphinx/ext/extlinks.py
@@ -61,4 +61,4 @@ def setup_link_roles(app):
 def setup(app):
     app.add_config_value('extlinks', {}, 'env')
     app.connect('builder-inited', setup_link_roles)
-    return {'version': sphinx.__version__, 'parallel_read_safe': True}
+    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
diff --git a/sphinx/ext/graphviz.py b/sphinx/ext/graphviz.py
index 56acf7fec..3970edc07 100644
--- a/sphinx/ext/graphviz.py
+++ b/sphinx/ext/graphviz.py
@@ -317,4 +317,4 @@ def setup(app):
     app.add_config_value('graphviz_dot', 'dot', 'html')
     app.add_config_value('graphviz_dot_args', [], 'html')
     app.add_config_value('graphviz_output_format', 'png', 'html')
-    return {'version': sphinx.__version__, 'parallel_read_safe': True}
+    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
diff --git a/sphinx/ext/ifconfig.py b/sphinx/ext/ifconfig.py
index e65943769..3c77566ef 100644
--- a/sphinx/ext/ifconfig.py
+++ b/sphinx/ext/ifconfig.py
@@ -75,4 +75,4 @@ def setup(app):
     app.add_node(ifconfig)
     app.add_directive('ifconfig', IfConfig)
     app.connect('doctree-resolved', process_ifconfig_nodes)
-    return {'version': sphinx.__version__, 'parallel_read_safe': True}
+    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
diff --git a/sphinx/ext/inheritance_diagram.py b/sphinx/ext/inheritance_diagram.py
index 05eb15895..f618aaf15 100644
--- a/sphinx/ext/inheritance_diagram.py
+++ b/sphinx/ext/inheritance_diagram.py
@@ -408,4 +408,4 @@ def setup(app):
     app.add_config_value('inheritance_graph_attrs', {}, False),
     app.add_config_value('inheritance_node_attrs', {}, False),
     app.add_config_value('inheritance_edge_attrs', {}, False),
-    return {'version': sphinx.__version__, 'parallel_read_safe': True}
+    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
diff --git a/sphinx/ext/intersphinx.py b/sphinx/ext/intersphinx.py
index 60743c496..bbfeab663 100644
--- a/sphinx/ext/intersphinx.py
+++ b/sphinx/ext/intersphinx.py
@@ -282,4 +282,4 @@ def setup(app):
     app.add_config_value('intersphinx_cache_limit', 5, False)
     app.connect('missing-reference', missing_reference)
     app.connect('builder-inited', load_mappings)
-    return {'version': sphinx.__version__, 'parallel_read_safe': True}
+    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
diff --git a/sphinx/ext/jsmath.py b/sphinx/ext/jsmath.py
index 399c9bc09..2cc661430 100644
--- a/sphinx/ext/jsmath.py
+++ b/sphinx/ext/jsmath.py
@@ -59,4 +59,4 @@ def setup(app):
     mathbase_setup(app, (html_visit_math, None), (html_visit_displaymath, None))
     app.add_config_value('jsmath_path', '', False)
     app.connect('builder-inited', builder_inited)
-    return {'version': sphinx.__version__, 'parallel_read_safe': True}
+    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
diff --git a/sphinx/ext/linkcode.py b/sphinx/ext/linkcode.py
index 336c4c3dc..b0ee5e43e 100644
--- a/sphinx/ext/linkcode.py
+++ b/sphinx/ext/linkcode.py
@@ -74,4 +74,4 @@ def doctree_read(app, doctree):
 def setup(app):
     app.connect('doctree-read', doctree_read)
     app.add_config_value('linkcode_resolve', None, '')
-    return {'version': sphinx.__version__, 'parallel_read_safe': True}
+    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
diff --git a/sphinx/ext/mathjax.py b/sphinx/ext/mathjax.py
index e967cd75e..d512db465 100644
--- a/sphinx/ext/mathjax.py
+++ b/sphinx/ext/mathjax.py
@@ -71,4 +71,4 @@ def setup(app):
     app.add_config_value('mathjax_inline', [r'\(', r'\)'], 'html')
     app.add_config_value('mathjax_display', [r'\[', r'\]'], 'html')
     app.connect('builder-inited', builder_inited)
-    return {'version': sphinx.__version__, 'parallel_read_safe': True}
+    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
diff --git a/sphinx/ext/napoleon/__init__.py b/sphinx/ext/napoleon/__init__.py
index 14a061158..d96c66a76 100644
--- a/sphinx/ext/napoleon/__init__.py
+++ b/sphinx/ext/napoleon/__init__.py
@@ -256,7 +256,7 @@ def setup(app):
 
     for name, (default, rebuild) in iteritems(Config._config_values):
         app.add_config_value(name, default, rebuild)
-    return {'version': sphinx.__version__, 'parallel_read_safe': True}
+    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
 
 
 def _process_docstring(app, what, name, obj, options, lines):
diff --git a/sphinx/ext/pngmath.py b/sphinx/ext/pngmath.py
index dd713cf4f..8ef860f80 100644
--- a/sphinx/ext/pngmath.py
+++ b/sphinx/ext/pngmath.py
@@ -247,4 +247,4 @@ def setup(app):
     app.add_config_value('pngmath_latex_preamble', '', 'html')
     app.add_config_value('pngmath_add_tooltips', True, 'html')
     app.connect('build-finished', cleanup_tempdir)
-    return {'version': sphinx.__version__, 'parallel_read_safe': True}
+    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
diff --git a/sphinx/ext/todo.py b/sphinx/ext/todo.py
index 6f4d366c7..64359c9b0 100644
--- a/sphinx/ext/todo.py
+++ b/sphinx/ext/todo.py
@@ -188,4 +188,4 @@ def setup(app):
     app.connect('doctree-resolved', process_todo_nodes)
     app.connect('env-purge-doc', purge_todos)
     app.connect('env-merge-info', merge_info)
-    return {'version': sphinx.__version__, 'parallel_read_safe': True}
+    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
diff --git a/sphinx/ext/viewcode.py b/sphinx/ext/viewcode.py
index a79078b50..e6af4f550 100644
--- a/sphinx/ext/viewcode.py
+++ b/sphinx/ext/viewcode.py
@@ -217,4 +217,4 @@ def setup(app):
     app.connect('missing-reference', missing_reference)
     # app.add_config_value('viewcode_include_modules', [], 'env')
     # app.add_config_value('viewcode_exclude_modules', [], 'env')
-    return {'version': sphinx.__version__, 'parallel_read_safe': True}
+    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
diff --git a/sphinx/make_mode.py b/sphinx/make_mode.py
index 77ce7373d..7d239f51c 100644
--- a/sphinx/make_mode.py
+++ b/sphinx/make_mode.py
@@ -78,7 +78,7 @@ class Make(object):
             shutil.rmtree(self.builddir_join(item))
 
     def build_help(self):
-        print(bold("Sphinx v%s" % sphinx.__version__))
+        print(bold("Sphinx v%s" % sphinx.__display_version__))
         print("Please use `make %s' where %s is one of" % ((blue('target'),)*2))
         for osname, bname, description in BUILDERS:
             if not osname or os.name == osname:
diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py
index b13d1810d..0548f69c5 100644
--- a/sphinx/quickstart.py
+++ b/sphinx/quickstart.py
@@ -33,7 +33,7 @@ from six.moves import input
 from six.moves.urllib.parse import quote as urlquote
 from docutils.utils import column_width
 
-from sphinx import __version__
+from sphinx import __display_version__
 from sphinx.util.osutil import make_filename
 from sphinx.util.console import purple, bold, red, turquoise, \
     nocolor, color_terminal
@@ -1135,7 +1135,7 @@ def ask_user(d):
     * batchfile: make command file
     """
 
-    print(bold('Welcome to the Sphinx %s quickstart utility.') % __version__)
+    print(bold('Welcome to the Sphinx %s quickstart utility.') % __display_version__)
     print('''
 Please enter values for the following settings (just press Enter to
 accept a default value, if one is given in brackets).''')
@@ -1405,7 +1405,7 @@ def usage(argv, msg=None):
 USAGE = """\
 Sphinx v%s
 Usage: %%prog [options] [projectdir]
-""" % __version__
+""" % __display_version__
 
 EPILOG = """\
 For more information, visit <http://sphinx-doc.org/>.
@@ -1459,7 +1459,7 @@ def main(argv=sys.argv):
         nocolor()
 
     parser = optparse.OptionParser(USAGE, epilog=EPILOG,
-                                   version='Sphinx v%s' % __version__,
+                                   version='Sphinx v%s' % __display_version__,
                                    formatter=MyFormatter())
     parser.add_option('-q', '--quiet', action='store_true', dest='quiet',
                       default=False,
diff --git a/sphinx/util/__init__.py b/sphinx/util/__init__.py
index 1b483f0f7..e23539fdc 100644
--- a/sphinx/util/__init__.py
+++ b/sphinx/util/__init__.py
@@ -207,7 +207,7 @@ def save_traceback(app):
             '#   %s' % strip_colors(force_decode(s, 'utf-8')).strip()
             for s in app.messagelog)
     os.write(fd, (_DEBUG_HEADER %
-                  (sphinx.__version__,
+                  (sphinx.__display_version__,
                    platform.python_version(),
                    platform.python_implementation(),
                    docutils.__version__, docutils.__version_details__,
diff --git a/sphinx/writers/texinfo.py b/sphinx/writers/texinfo.py
index d46769727..c066a3900 100644
--- a/sphinx/writers/texinfo.py
+++ b/sphinx/writers/texinfo.py
@@ -17,7 +17,7 @@ from six import itervalues
 from six.moves import range
 from docutils import nodes, writers
 
-from sphinx import addnodes, __version__
+from sphinx import addnodes, __display_version__
 from sphinx.locale import admonitionlabels, _
 from sphinx.util import ustrftime
 from sphinx.writers.latex import collected_footnote
@@ -39,7 +39,7 @@ TEMPLATE = """\
 @setfilename %(filename)s
 @documentencoding UTF-8
 @ifinfo
-@*Generated by Sphinx """ + __version__ + """.@*
+@*Generated by Sphinx """ + __display_version__ + """.@*
 @end ifinfo
 @settitle %(title)s
 @defindex ge
diff --git a/tests/test_build_html.py b/tests/test_build_html.py
index 572b4e50d..3ee89b72b 100644
--- a/tests/test_build_html.py
+++ b/tests/test_build_html.py
@@ -15,7 +15,7 @@ import re
 from six import PY3, iteritems
 from six.moves import html_entities
 
-from sphinx import __version__
+from sphinx import __display_version__
 from util import remove_unicode_literals, gen_with_app
 from etree13 import ElementTree as ET
 
@@ -347,7 +347,7 @@ def check_static_entries(outdir):
     assert (staticdir / 'subdir' / 'foo.css').isfile()
     # a file from a file entry in html_static_path
     assert (staticdir / 'templated.css').isfile()
-    assert (staticdir / 'templated.css').text().splitlines()[1] == __version__
+    assert (staticdir / 'templated.css').text().splitlines()[1] == __display_version__
     # a file from _static, but matches exclude_patterns
     assert not (staticdir / 'excluded.css').exists()