Merge branch 'refname' into stable

.gitlab-ci.yml

@@ -38,7 +38,7 @@ check for dependencies installed:
 build documentation:
   stage: test
   script:
-    - make -C doc realclean; make -C doc html SPHINXOPTS='-A website_deploy=True -n -W' REFNAME="${CI_COMMIT_TAG:-$CI_COMMIT_SHA}" SOURCE_URL="$CI_PROJECT_URL"/blob
+    - make -C doc realclean; make -C doc html SPHINXOPTS='-A website_deploy=True -n -W' SOURCE_LINK_TEMPLATE="$CI_PROJECT_URL"/blob/$$r/$$f
   artifacts:
     paths:
       - doc/build/html/

RELEASE.rst

@@ -112,7 +112,7 @@ Building the documentation requires 'sphinx' and a Latex installation.
 First build the HTML and PDF documentation::
 
     ./setup.py build
-    make -C doc realclean html latex SPHINXOPTS='-A website_deploy=True -n -W' REFNAME="<version>"
+    make -C doc realclean html latex SPHINXOPTS='-A website_deploy=True -n -W'
     cd doc/build/latex
     make all-pdf
 

doc/source/conf.py

@@ -11,8 +11,9 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
-
+import sys
+import os
+import string
 from distutils.util import get_platform
 sys.path.insert(0, "../../build/lib.{0}-{1}.{2}".format(
         get_platform(), *sys.version_info[:2]))
@@ -298,8 +299,18 @@ def linkcode_resolve(domain, info):
         filename = 'kwant/%s#L%d-%d' % find_source()
     except Exception:
         filename = info['module'].replace('.', '/') + '.py'
-    source_branch = os.environ.get('REFNAME', 'master')
-    url = os.environ.get('SOURCE_URL',
-                         "https://gitlab.kwant-project.org/kwant/kwant/blob")
 
-    return "{}/{}/{}".format(url, source_branch, filename)
+    # The following relies on the documented format of kwant.__version__.
+    rel = release.rstrip('.dirty')
+    if '.dev' in rel:
+        try:
+            refname = rel[rel.index('+g') + 2:]
+        except ValueError:
+            return
+    else:
+        refname = 'v' + rel
+
+    templ = os.environ.get(
+        "SOURCE_LINK_TEMPLATE",
+        "https://gitlab.kwant-project.org/kwant/kwant/blob/$r/$f")
+    return string.Template(templ).safe_substitute(r=refname, f=filename)

doc/source/reference/kwant.rst

@@ -9,7 +9,21 @@ Otherwise, this package has only very limited functionality of its own.
 
 Generic functionality
 ---------------------
+..
+   TODO: Once we depend on Sphinx 1.8, the documentation of __version__ can be
+   put into the "docstring": https://github.com/sphinx-doc/sphinx/issues/344
+
 The version of Kwant is available under the name ``__version__``.
+This string respects `PEP 440 <https://www.python.org/dev/peps/pep-0440/>`_
+and has the following format
+
+- Released version: '1.3.0', '1.3.1', etc.
+- Alpha version: '1.2.0a0', '1.2.0a1', etc.
+- Beta version: '1.1.0b0', '1.1.0b1', etc.
+- Development version (derived from ``git describe --first-parent --dirty``):
+  '1.3.2.dev27+gdecf6893', '1.1.1.dev10+gabcd012.dirty', etc.
+- Development version with incomplete information: 'unknown',
+  'unknown+g0123abc', etc.
 
 .. autosummary::
    :toctree: generated/