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