Static Sites with Sphinx and Markdown Transcripts
Lecture: More on linking
0:00 As you can imagine there's a lot more linking power in Sphinx beyond.
0:06 just rolls. First if you really liked that thing about linking to a heading but you
0:14 find it too much work to preface all of your headings with that syntax for a
0:19 link, MyST has a setting for auto generating header anchors from the heading words.
0:30 And this can make it very convenient to just get that for free everywhere that you
0:35 use a heading. But I consider it a little bit iffy because those identifiers
0:41 don't prove to be all that stable.
0:43 Remember they're going to be published as part of your website and outside people might be
0:49 linking to it as well. And if you decide to change the wording of one
0:53 of your headings, then all of your roles and all of your external links will
1:01 be broken. It's just not a very stable identify.
1:03 Sphinx is known for documentation and it's auto doc tool generates all kinds of linkable
1:10 targets in your source code.
1:12 We're going to have a section devoted to documentation and auto doc but for now just
1:18 understand that you point something like Sphinx at a big pile of code and it not
1:25 only turns it into words and highlighting on the screen,
1:29 it turns it into structure including roles.
1:34 Linkable targets that can be pointed to as stable,
1:38 identifiers from within your narrative documentation.
1:43 We've seen a little bit about the toctree directive and it gets your files listed
1:48 in a certain order but it also helps on linking because thanks to the order in
1:55 the nesting, it will generate previous and next links that you can use in your
2:00 templates as well as up to go up A level and top to go all the
2:06 way to the top and finally linking to external URL's that aren't managed by Sphinx
2:11 that's a part of your website.
2:14 But how are you going to find out if those links are broken,
2:17 Sphinx ships with a tool that you can use and run make link check.
2:22 And it will go through your built documentation and try to find any places that point
2:29 to a URL on the web, which no longer works