id	summary	reporter	owner	description	type	status	priority	milestone	component	resolution	keywords	cc	branch	branch_author	launchpad_bug
4621	lore2sphinx should make pretty links to included files.	Screwtape		"Currently, when Lore includes a separate file as a code-example (such as the new module template in the [http://twistedmatrix.com/documents/current/core/development/policy/coding-standard.html Coding Standard]), it adds a hyperlink to the file as a caption, styled as part of the same block and clearly different from the body text.

In the existing [http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/core/development/policy/coding-standard.html#modules Sphinx-based documents], included files mention the path to the file as an ordinary body-text paragraph above the block, without any hyperlink or separate formatting.

I looked at the Sphinx docs and couldn't find any obvious way to say 'include this other document and decorate it with a hyperlink to the source'. If there is such a thing, we should use it; otherwise `lore2sphinx` should just generate the hyperlink directive as well as the include directive; maybe with some extra ""download the source of this example from $PATH_TO_FILE"" text. Bonus points if the hyperlink emerges from `rst2html` with a HTML class attribute so we can decorate it in the online docs, and is hidden from `rst2pdf` and other non-interactive media.

Justifications for this enhancement include:

 * Prettier docs
 * Feature-parity with Lore
 * Not having to explain the unusual behaviour to every reviewer that reviews an ""Improve lore2sphinx buildbot results for FOO"" ticket. :)"	enhancement	assigned	normal	Lore to Sphinx	core		documentation	khorn thijs