Opened 4 years ago

Last modified 13 months ago

#4621 enhancement assigned

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 Branch:
Author: Launchpad Bug:

Description

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 (8)

comment:1 Changed 4 years ago by khorn

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

comment:3 Changed 4 years ago by thijs

  • Cc thijs added

comment:4 Changed 4 years ago by thijs

  • Owner changed from glyph to thijs
  • Status changed from new to assigned

comment:5 Changed 4 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 4 years ago by thijs

Thanks, I added a note to the ticket.

comment:7 Changed 4 years ago by <automation>

  • Owner thijs deleted

comment:8 Changed 13 months 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.

Compare:

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

Note: See TracTickets for help on using tickets.