Opened 6 years ago

Closed 12 days ago

#4621 enhancement closed wontfix (wontfix)

lore2sphinx should make pretty links to included files.

Reported by: Screwtape Owned by:
Priority: normal Milestone: Lore to Sphinx
Component: core Keywords: documentation
Cc: khorn, Thijs Triemstra Branch:


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

Change History (9)

comment:1 Changed 6 years ago by khorn

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

comment:3 Changed 6 years ago by Thijs Triemstra

Cc: Thijs Triemstra added

comment:4 Changed 6 years ago by Thijs Triemstra

Owner: changed from Glyph to Thijs Triemstra
Status: newassigned

comment:5 Changed 6 years ago by 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.

comment:6 Changed 6 years ago by Thijs Triemstra

Thanks, I added a note to the ticket.

comment:7 Changed 6 years ago by <automation>

Owner: Thijs Triemstra deleted

comment:8 Changed 3 years ago by Glyph

While we're losing a tiny bit of functionality here (the textual label for the file, as opposed to just the file's name), we do have a link, and it is pretty.


I'm inclined to say "nevermind" and we can just get this later when someone cares enough to fix the sphinx bug.

comment:9 Changed 12 days ago by Glyph

Resolution: wontfix
Status: assignedclosed

lore2sphinx is as good as it's gonna get, so closing these tickets that reference it.

Note: See TracTickets for help on using tickets.