Adding links HTML <->Slides (manually)

[AlbertMietus]

It would be very nice to be able to insert a (or several) link(s) from the html-build to the slide-build; not to the "same" location (which can be done automatically), but to any place/ref I like.

Like it is possible from html to html (or slide to slide), using std RST notation.

UseCase: For trainings I will use hieroglyph slides and put them online, with html-handouts. They can be build from the same rst-source; or other files. However, html pages are typically very spares. That is logically for whoever expect a slide-show, but to other users, landing on the html-page, that can be strange.

Currently, I simply add warning (ifnotsides:: warning:: ...read the slides... ). But I would love to have slides be an hyperlink to those slides.

The question is how?

[nyergler]

I suspect the way to do it is with a custom Sphinx role. Roles allow you to apply custom processing to inline text (as opposed to directives -- like ifnotslides, nextslide, etc -- which operate at a paragraph level). There's a somewhat dated -- but still accurate, I believe -- blog post about writing custom roles: http://doughellmann.com/2010/05/09/defining-custom-roles-in-sphinx.html

I sort of think something like

:slidelink:`title`

(or number) would be reasonable syntax. The wrinkle is going to be how to resolve the slide links if you want to allow links to arbitrary slides. Maybe all we need to do is the normal section linking, with a different URL base (ie, to slides.html instead of the "notes" html output).

Thoughts?

[AlbertMietus]

Assuming both html and slides are build from the same sources (otherwise it useless), a build "knows" all refs (for normal -internal-- links). By fiddling the URL-base the other ref can be calculated. Here we can reuse current html<->slide links code/concept.

I like the :slidelink:notation, for pointing to the slide. Let add also create `:handouts:`<ref> to point from slide to html. As Dough's blog show, we can use the same function for both

The big questions is what should the roles deliver when we are not building both slides and html? Creating dangling pointers is ugly. And the code itself can never 'know'. So we need a config/flag for that. But I guess we can (re)use slide_link_to_html and slide_link_html_to_slides. Or do you like to keep the separate?

Sounds like nice feature. The only downside is: I probably don't have time to implement it :-)

[nyergler]

You're right re: refs, although the slide builder generates new refs when you use things like the nextslide directive. Those don't exist in the doctree when you're using the html builder, so those might be problematic. But even limited to "real" refs, this seems useful.

I sort of think it should be a different config flag: those two control whether or not we add the title-level slide <-> html links, this seems a little different. One option would be to read the environment in conf.py to figure out if we're building both, and then add a Makefile target for building both that sets the environment flag. We could update the default conf/Makefile generated by quickstart to support this seamlessly. That way there's little configuration needed by the author.

[AlbertMietus]

I prefer to have a explicit config-flag. Reading the env and guessing what I mean, usually goed wrong. And I don’t use the standard makefile anyhow. Also, we have the use-cased where somebody only builds one of two, while the other is still valid; then the links should work

My proposal is to make two (boolean) flags slide_link_handouts and slide_link_slidelink; and default them to True. Or perhaps to the value of slide_link_to_html and slide_link_html_to_slides. So, by default the links will be made!

This way, the configuration is small. It just works, as one expects when using the roles. It will be hard to create a dangling link, as the author has to use one of those new roles!

The big question remains however: which text to use instead (when the flag of off). The best way to do so, adopting the std ref notation: http://sphinx-doc.org/markup/inline.html#xref-syntax

An example (Writing rst in md isn't fun; the code below works in preview; but not in real. Guess you can guess ...)

.. my_welcome
WELCOME
=========

.. ifnotslides::

  .. warning:: This is a HTML/text-version of the corresponding (HTML/Web) :slide link:`slides <my_welcome>`.

When off (and using title syntax) the text simply ends with slides. (no link). Without that notation, the backquoted text is used (again no link)

That will work for me.