ebu-tt-live-toolkit icon indicating copy to clipboard operation
ebu-tt-live-toolkit copied to clipboard

Published 20 hours ago • verified publisher icon ebu

[DOCUMENTATION] Add back link to project home page from built docs

Open nigelmegitt opened this issue 7 years ago • 7 comments

When you traverse from the project home page to the the documentation there are no links back. Add one, preferably in the blue panel in the top left.

nigelmegitt avatar Jul 13 '17 16:07 nigelmegitt

Notes:

the home page looks URL is:

http://ebu.github.io/ebu-tt-live-toolkit/

the built documentation ends up at:

http://ebu.github.io/ebu-tt-live-toolkit/html/index.html

So the back link is effectively ../.. or ../index.html though that backwards links always seem "dodgy" somehow, and I'm not sure how standard they are. It seems like bad practice to use them if avoidable.

nigelmegitt avatar Sep 15 '17 14:09 nigelmegitt

It seems like the most likely way to be able to achieve this is to subclass the template as documented for Sphinx, but my initial attempts resulted in nothing happening, so nothing to commit after looking at this in various different ways for an hour or so. Probably won't come back to this for a while now, if anyone else wants to take a go.

nigelmegitt avatar Sep 15 '17 18:09 nigelmegitt

It seems that links to any files in an ancestor folder are not possible. I tried myself (without success) and also found https://github.com/sphinx-doc/sphinx/issues/701.

spoeschel avatar Jan 22 '20 14:01 spoeschel

Grr that's frustrating @spoeschel ! Thanks for looking.

nigelmegitt avatar Jan 22 '20 14:01 nigelmegitt

It is a bit annoying that such links aren't possible. On the other hand, it is probably OK to not have a link back, as all the other (external) link targets the project homepage refers to don't have back links either.

spoeschel avatar Jan 23 '20 07:01 spoeschel

I guess one easy but less elegant fix is to link to a non-relative URL and label it as the public built one, and describe where the locally built one will end up with a path string that isn't a link. What do you think @spoeschel ?

nigelmegitt avatar Jan 23 '20 10:01 nigelmegitt

This sounds good.

describe where the locally built one will end up with a path string that isn't a link

Would this description be on a separate page, as part of the Sphinx documentation? If so, at least within that page it would be possible to (also) add a link that references the parent folder - only the toctree directive is restricted in this aspect.

Or would it maybe be enough to just add the local link back to near the top of index.rst?

spoeschel avatar Jan 23 '20 12:01 spoeschel