From fb511a015aa47c943c5dc1286f58743fca307b1c Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 24 Feb 2009 13:38:15 +0100 Subject: [PATCH] Paths to literal include files and download files can now be absolute too. --- CHANGES | 5 +++-- doc/markup/code.rst | 7 +++++-- doc/markup/inline.rst | 9 ++++++--- sphinx/directives/code.py | 12 +++++++----- sphinx/environment.py | 16 ++++++++-------- tests/root/contents.txt | 1 + tests/root/special/code.py | 2 ++ tests/root/subdir/includes.txt | 12 ++++++++++++ tests/test_build.py | 5 +++++ 9 files changed, 49 insertions(+), 20 deletions(-) create mode 100644 tests/root/special/code.py create mode 100644 tests/root/subdir/includes.txt diff --git a/CHANGES b/CHANGES index 794af9b34..3f71d1ae1 100644 --- a/CHANGES +++ b/CHANGES @@ -52,8 +52,9 @@ New features added the directive -- this allows you to define your document structure, but place the links yourself. - - Image paths can now be absolute (like ``/images/foo.png``). - They are treated as relative to the top source directory. + - Paths to images, literal include files and download files + can now be absolute (like ``/images/foo.png``). They are + treated as relative to the top source directory. - #52: There is now a ``hlist`` directive, creating a compact list by placing distributing items into multiple columns. diff --git a/doc/markup/code.rst b/doc/markup/code.rst index 28f752365..93cd127ba 100644 --- a/doc/markup/code.rst +++ b/doc/markup/code.rst @@ -99,7 +99,9 @@ Includes .. literalinclude:: example.py - The file name is relative to the current file's path. + The file name is usually relative to the current file's path. However, if it + is absolute (starting with ``/``), it is relative to the top source + directory. The directive also supports the ``linenos`` flag option to switch on line numbers, and a ``language`` option to select a language different from the @@ -144,7 +146,8 @@ Includes .. versionadded:: 0.4.3 The ``encoding`` option. .. versionadded:: 0.6 - The ``pyobject``, ``lines``, ``start-after`` and ``end-before`` options. + The ``pyobject``, ``lines``, ``start-after`` and ``end-before`` options, + as well as support for absolute filenames. .. rubric:: Footnotes diff --git a/doc/markup/inline.rst b/doc/markup/inline.rst index 9f8a01a56..97b20da79 100644 --- a/doc/markup/inline.rst +++ b/doc/markup/inline.rst @@ -264,9 +264,12 @@ Referencing downloadable files See :download:`this example script <../example.py>`. - The given filename is relative to the directory the current source file is - contained in. The ``../example.py`` file will be copied to the output - directory, and a suitable link generated to it. + The given filename is usually relative to the directory the current source + file is contained in, but if it absolute (starting with ``/``), it is taken + as relative to the top source directory. + + The ``example.py`` file will be copied to the output directory, and a + suitable link generated to it. Other semantic markup diff --git a/sphinx/directives/code.py b/sphinx/directives/code.py index 70aecd83e..645bc7844 100644 --- a/sphinx/directives/code.py +++ b/sphinx/directives/code.py @@ -7,6 +7,7 @@ :license: BSD, see LICENSE for details. """ +import os import sys import codecs from os import path @@ -95,11 +96,12 @@ class LiteralInclude(Directive): return [document.reporter.warning('File insertion disabled', line=self.lineno)] env = document.settings.env - rel_fn = filename - sourcename = self.state_machine.input_lines.source( - self.lineno - self.state_machine.input_offset - 1) - source_dir = path.dirname(path.abspath(sourcename)) - fn = path.normpath(path.join(source_dir, rel_fn)) + if filename.startswith('/') or filename.startswith(os.sep): + rel_fn = filename[1:] + else: + docdir = path.dirname(env.doc2path(env.docname, base=None)) + rel_fn = path.normpath(path.join(docdir, filename)) + fn = path.join(env.srcdir, rel_fn) if 'pyobject' in self.options and 'lines' in self.options: return [document.reporter.warning( diff --git a/sphinx/environment.py b/sphinx/environment.py index 6d34eb61e..6deea1d5d 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -24,12 +24,10 @@ from glob import glob from string import ascii_uppercase as uppercase from itertools import izip, groupby try: - import hashlib - md5 = hashlib.md5 + from hashlib import md5 except ImportError: # 2.4 compatibility - import md5 - md5 = md5.new + from md5 import md5 from docutils import nodes from docutils.io import FileInput, NullOutput @@ -682,7 +680,12 @@ class BuildEnvironment: """ docdir = path.dirname(self.doc2path(docname, base=None)) for node in doctree.traverse(addnodes.download_reference): - filepath = path.normpath(path.join(docdir, node['reftarget'])) + targetname = node['reftarget'] + if targetname.startswith('/') or targetname.startswith(os.sep): + # absolute + filepath = targetname[1:] + else: + filepath = path.normpath(path.join(docdir, node['reftarget'])) self.dependencies.setdefault(docname, set()).add(filepath) if not os.access(path.join(self.srcdir, filepath), os.R_OK): self.warn(docname, 'Download file not readable: %s' % filepath, @@ -952,9 +955,6 @@ class BuildEnvironment: node.astext())) def note_dependency(self, filename): - basename = path.dirname(self.doc2path(self.docname, base=None)) - # this will do the right thing when filename is absolute too - filename = path.join(basename, filename) self.dependencies.setdefault(self.docname, set()).add(filename) # ------- diff --git a/tests/root/contents.txt b/tests/root/contents.txt index 719034ce2..0e52593e2 100644 --- a/tests/root/contents.txt +++ b/tests/root/contents.txt @@ -13,6 +13,7 @@ Contents: images subdir/images + subdir/includes includes markup desc diff --git a/tests/root/special/code.py b/tests/root/special/code.py new file mode 100644 index 000000000..70c48d2e7 --- /dev/null +++ b/tests/root/special/code.py @@ -0,0 +1,2 @@ +print "line 1" +print "line 2" diff --git a/tests/root/subdir/includes.txt b/tests/root/subdir/includes.txt new file mode 100644 index 000000000..3e1ae0d13 --- /dev/null +++ b/tests/root/subdir/includes.txt @@ -0,0 +1,12 @@ +Including in subdir +=================== + +.. absolute filename +.. literalinclude:: /special/code.py + :lines: 1 + +.. relative filename +.. literalinclude:: ../special/code.py + :lines: 2 + +Absolute :download:`/img.png` download. diff --git a/tests/test_build.py b/tests/test_build.py index b9d2c7793..f451b3052 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -70,6 +70,11 @@ HTML_XPATH = { ".//img[@src='../_images/img1.png']": '', ".//img[@src='../_images/rimg.png']": '', }, + 'subdir/includes.html': { + ".//pre/span": 'line 1', + ".//pre/span": 'line 2', + ".//a[@href='../_downloads/img.png']": '', + }, 'includes.html': { ".//pre": u'Max Strauß', ".//a[@href='_downloads/img.png']": '',