A diff parameter for literalinclude
Some of the Twisted tutorials / howto documents contain a narrative that refers to multiple versions of an example Python script. eg * https://twistedmatrix.com/documents/current/core/howto/tutorial/intro.html
The example may start as a simple hello world and each step of the tutorial may introduce a new class / function or modify part of the earlier script.
It would be nice if Sphinx had some way of highlighting only the changes between successive examples.
The most obvious solution that comes to mind, is to add a new "diff" parameter to literalinclude which references an earlier example script.
Then use difflib to produce a unified diff and pygments diff highlighting to color code the output eg
--- a/sphinx/directives/code.py Sun Mar 17 10:58:28 2013 +0900 +++ b/sphinx/directives/code.py Wed Mar 27 18:38:29 2013 +0000 @@ -105,9 +105,11 @@ 'prepend': directives.unchanged_required, 'append': directives.unchanged_required, 'emphasize-lines': directives.unchanged_required, + 'diff': directives.unchanged_required, } def run(self): document = self.state.document if not document.settings.file_insertion_enabled: return [document.reporter.warning('File insertion disabled', @@ -152,6 +154,25 @@ else: lines = lines[tags[objectname]-1 : tags[objectname]-1] + diffsource = self.options.get('diff') + if diffsource is not None: + from difflib import unified_diff + diff = unified_diff( + open(diffsource).readlines(), + open(filename).readlines(), + diffsource, + rel_filename) + lines = list(diff)
The trouble with this is that the Python syntax highlighting is lost. It would be even nicer if the files were first syntax highlighted for eg python then the differences computed and only the changed portions displayed with the line numbers from the original files.