Ticket #4621 enhancement assigned
lore2sphinx should make pretty links to included files.
|Reported by:||Screwtape||Owned by:|
|Priority:||normal||Milestone:||Lore to Sphinx|
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. :)