Commits

Georg Brandl  committed b151eb1

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

  • Participants
  • Parent commits 432ee1b

Comments (0)

Files changed (7)

   - #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:
 

File doc/rest.rst

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

File sphinx/directives/other.py

     :license: BSD, see LICENSE for details.
 """
 
+import os
+
 from docutils import nodes
 from docutils.parsers.rst import Directive, directives
 
         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)
 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

File tests/root/includes.txt

 
 .. include:: subdir/include.inc
 
+.. include:: /subdir/include.inc
+
 .. literalinclude:: literal.inc
    :language: python
 

File tests/root/subdir/includes.txt

 
 .. absolute image filename
 .. image:: /img.png
+
+.. absolute include filename
+.. include:: /test.inc

File tests/root/test.inc

+.. This file is included from subdir/includes.txt.
+
+This is an include file.

File tests/test_build_html.py

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