From f3c706edae42b6974543aad29bc85b196dd38200 Mon Sep 17 00:00:00 2001
From: Georg Brandl <georg@python.org>
Date: Sun, 30 May 2010 12:59:42 +0200
Subject: [PATCH] The ``include`` directive now supports absolute paths, which
 are interpreted as relative to the source directory.

---
 CHANGES                        |  2 ++
 doc/rest.rst                   | 12 +++++++-----
 sphinx/directives/other.py     | 19 +++++++++++++++++++
 tests/root/includes.txt        |  2 ++
 tests/root/subdir/includes.txt |  3 +++
 tests/root/test.inc            |  3 +++
 tests/test_build_html.py       |  1 +
 7 files changed, 37 insertions(+), 5 deletions(-)
 create mode 100644 tests/root/test.inc

diff --git a/CHANGES b/CHANGES
index 5be94f2fa..300f5fe28 100644
--- a/CHANGES
+++ b/CHANGES
@@ -51,6 +51,8 @@ Features added
   - #284: All docinfo metadata is now put into the document metadata, not
     just the author.
   - The ``ref`` role can now also reference tables by caption.
+  - The ``include`` directive now supports absolute paths, which are
+    interpreted as relative to the source directory.
 
 * Configuration:
 
diff --git a/doc/rest.rst b/doc/rest.rst
index 3a14ac183..2b6eee6b4 100644
--- a/doc/rest.rst
+++ b/doc/rest.rst
@@ -297,6 +297,8 @@ Docutils supports the following directives:
 
   - :dudir:`raw` (include raw target-format markup)
   - :dudir:`include` (include reStructuredText from another file)
+    -- in Sphinx, when given an absolute include file path, this directive takes
+    it as relative to the source directory
   - :dudir:`class` (assign a class attribute to the next element) [1]_
 
 * HTML specifics:
@@ -426,11 +428,11 @@ or this::
 See the :duref:`reST reference for substitutions <substitution-definitions>`
 for details.
 
-If you want to use some substitutions for all documents, put them into a
-separate file and include it into all documents you want to use them in, using
-the :rst:dir:`include` directive.  Be sure to give the include file a file name
-extension differing from that of other source files, to avoid Sphinx finding it
-as a standalone document.
+If you want to use some substitutions for all documents, put them into
+:confval:`rst_prolog` or put them into a separate file and include it into all
+documents you want to use them in, using the :rst:dir:`include` directive.  (Be
+sure to give the include file a file name extension differing from that of other
+source files, to avoid Sphinx finding it as a standalone document.)
 
 Sphinx defines some default substitutions, see :ref:`default-substitutions`.
 
diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py
index 138d10c8b..5ce1ce1aa 100644
--- a/sphinx/directives/other.py
+++ b/sphinx/directives/other.py
@@ -7,6 +7,8 @@
     :license: BSD, see LICENSE for details.
 """
 
+import os
+
 from docutils import nodes
 from docutils.parsers.rst import Directive, directives
 
@@ -367,6 +369,22 @@ class Only(Directive):
         return [node]
 
 
+from docutils.parsers.rst.directives.misc import Include as BaseInclude
+
+class Include(BaseInclude):
+    """
+    Like the standard "Include" directive, but interprets absolute paths
+    correctly.
+    """
+
+    def run(self):
+        if self.arguments[0].startswith('/') or \
+               self.arguments[0].startswith(os.sep):
+            env = self.state.document.settings.env
+            self.arguments[0] = os.path.join(env.srcdir, self.arguments[0][1:])
+        return BaseInclude.run(self)
+
+
 directives.register_directive('toctree', TocTree)
 directives.register_directive('sectionauthor', Author)
 directives.register_directive('moduleauthor', Author)
@@ -381,6 +399,7 @@ directives.register_directive('centered', Centered)
 directives.register_directive('acks', Acks)
 directives.register_directive('hlist', HList)
 directives.register_directive('only', Only)
+directives.register_directive('include', Include)
 
 # register the standard rst class directive under a different name
 from docutils.parsers.rst.directives.misc import Class
diff --git a/tests/root/includes.txt b/tests/root/includes.txt
index 85cf19701..904f06773 100644
--- a/tests/root/includes.txt
+++ b/tests/root/includes.txt
@@ -10,6 +10,8 @@ Test file and literal inclusion
 
 .. include:: subdir/include.inc
 
+.. include:: /subdir/include.inc
+
 .. literalinclude:: literal.inc
    :language: python
 
diff --git a/tests/root/subdir/includes.txt b/tests/root/subdir/includes.txt
index 53a6bd29a..627dcfb9b 100644
--- a/tests/root/subdir/includes.txt
+++ b/tests/root/subdir/includes.txt
@@ -13,3 +13,6 @@ Absolute :download:`/img.png` download.
 
 .. absolute image filename
 .. image:: /img.png
+
+.. absolute include filename
+.. include:: /test.inc
diff --git a/tests/root/test.inc b/tests/root/test.inc
new file mode 100644
index 000000000..b8fdb932e
--- /dev/null
+++ b/tests/root/test.inc
@@ -0,0 +1,3 @@
+.. This file is included from subdir/includes.txt.
+
+This is an include file.
\ No newline at end of file
diff --git a/tests/test_build_html.py b/tests/test_build_html.py
index 93a015daf..2e00bb991 100644
--- a/tests/test_build_html.py
+++ b/tests/test_build_html.py
@@ -62,6 +62,7 @@ HTML_XPATH = {
     'subdir/includes.html': {
         ".//a[@href='../_downloads/img.png']": '',
         ".//img[@src='../_images/img.png']": '',
+        ".//p": 'This is an include file.',
     },
     'includes.html': {
         ".//pre": u'Max Strauß',