Close #4: Added a `:download:` role that marks a non-document file

for inclusion into the HTML output and links to it.

tests/root/includes.txt

@@ -14,3 +14,11 @@ Test file and literal inclusion
    :encoding: latin-1
 .. include:: wrongenc.inc
    :encoding: latin-1
+
+
+Testing downloadable files
+==========================
+
+Download :download:`img.png` here.
+Download :download:`this <subdir/img.png>` there.
+Don't download :download:`this <nonexisting.png>`.

tests/test_build.py

@@ -32,6 +32,7 @@ WARNING: %(root)s/images.txt:9: Image file not readable: foo.png
 WARNING: %(root)s/images.txt:23: Nonlocal image URI found: http://www.python.org/logo.png
 WARNING: %(root)s/includes.txt:: (WARNING/2) Encoding 'utf-8' used for reading included \
 file u'wrongenc.inc' seems to be wrong, try giving an :encoding: option
+WARNING: %(root)s/includes.txt:34: Download file not readable: nonexisting.png
 """
 
 HTML_WARNINGS = ENV_WARNINGS + """\
@@ -58,6 +59,8 @@ HTML_XPATH = {
     'includes.html': {
         ".//pre/span[@class='s']": u'üöä',
         ".//pre": u'Max Strauß',
+        ".//a[@href='_downloads/img.png']": '',
+        ".//a[@href='_downloads/img1.png']": '',
     },
     'autodoc.html': {
         ".//dt[@id='test_autodoc.Class']": '',

tests/test_env.py

@@ -77,11 +77,13 @@ def test_second_update():
     (root / 'new.txt').write_text('New file\n========\n')
     it = env.update(app.config, app.srcdir, app.doctreedir, app)
     msg = it.next()
-    assert '1 added, 1 changed, 1 removed' in msg
+    assert '1 added, 2 changed, 1 removed' in msg
     docnames = set()
     for docname in it:
         docnames.add(docname)
-    assert docnames == set(['contents', 'new'])
+    # "includes" is in there because it contains a reference to a nonexisting
+    # downloadable file, which is given another chance to exist
+    assert docnames == set(['contents', 'new', 'includes'])
     assert 'images' not in env.all_docs
     assert 'images' not in env.found_docs