The `include` directive now supports absolute paths, which are interpreted as relative to the source directory.

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:
 

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`.
 

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

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
 

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

tests/root/test.inc

@@ -0,0 +1,3 @@
+.. This file is included from subdir/includes.txt.
+
+This is an include file.

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ß',