Static Sites with Sphinx and Markdown Transcripts
Chapter: Linking between sites
Lecture: Linking to remote documents
0:00 We have a static website and we're riding content that has rich linking within that website Now that we've set up
0:10 Inter Sphinx we can link to content on the Sphinx site as if it were local Let's see this in action first.
0:19 I want to demonstrate a full build of Sphinx from the command line so you can see the output that gets the inventory file from the Sphinx website.
0:33 So when I run the Sphinx build command a lot of the output that it dumps to the console and that includes loading inter sphinx inventory from the
0:48 URL. We specified up in the conf file so that's what it's doing behind the scenes is it checks to see if it has any of these objects.inv
1:00 files that need to be downloaded, retrieves them and associates them with a key of Sphinx. Now back in my about us document.
1:13 I might want to link to something that says we're using Sphinx and we're using Sphinx roles and how powerful they are.
1:23 So I could do it the traditional external link way with markdown where you put the link text and then you put a.
1:32 URL. But that doesn't give me any of the sphinx goodness. First you know that's a long. URL. But what if we typed it wrong?
1:41 Would we get any warnings? No we would have to run some link checker. What if the link what if the Sphinx stocks get reorganized so that it's not at
1:51 that location anymore. It's at some other location. Well with roles. You can hide the internal structure just by putting a semantic label
2:00 on things. And wouldn't it be great to apply that to external content and then
2:07 finally it's no fun thinking about this link text which might change and get out of
2:12 date with what the remote page says is the meaning of that link target. Now the first of the three of these points can be solved with a separate link
2:23 check but it's more work and won't help with some of this more semantic stuff. So let's take a look at how we would do this with a sphinx roll.
2:33 Thanks to 'interphinx'. So first thing I'll do is delete this really long URL . I'll leave the link text in there.
2:44 But all I need to say now is that prefix that I had in the conf file, a colon and then the role that I'm pointing to.
2:55 So I will save that and I'll go back to my browser and I'll look at the bottom of my about us page and I'll see that I now have a link
3:13 that takes me to this. URL. I didn't have to memorize some really long H to blah blah blah. And in fact if I go back to my text I can
3:24 do what you hope we could do which is leave out the link text and let the content on the other end hand over the title.
3:36 Save it go back to my document in the browser, see what it reloaded as. And it gave me the link text of the thing
3:47 that I was linking to. What we also saw was that I wasn't linking to a remote document in its title.
3:57 I was linking a deep link into a section in the remote document and getting the
4:04 link text from that section heading now as wrap up and as a reminder if you link to something that is broken,
4:13 if I put this then my sphinx build would actually warn me that I have a broken link if I linked to this but the remote side changed it.
4:26 I would also get a warning saying that I link to something that doesn't exist.
4:30 This is something that really doesn't exist in other static site generators and is a very useful tool.