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

[khorn]

see  this thread on the sphinx list for some ideas and discussion

[khorn]

also  this sphinx ticket

[khorn]

When Sphinx ticket #541 is complete, we should have this for free. The Sphinx ticket has a patch, it looks like it's just waiting for someone on the Sphinx project to merge it.

[thijs]

Thanks, I added a note to the  ticket.