Static Sites with Sphinx and Markdown Transcripts
Chapter: Documenting Code
Lecture: Including code from a file

Login or purchase this course to watch this video and the rest of the course contents.
0:00 We just showed embedding code examples into a markdown document.
0:05 I almost never want to do that because I'm in the middle of a markdown document
0:12 and all of my python coding tooling,
0:15 syntax highlighting, all of that basically doesn't work that well anymore.
0:20 I want to write a python file and then I want to include that python file
0:24 into the document and then that lets me do things like write tests for the python
0:28 file to make sure I haven't broken anything.
0:31 So instead of code block I generally use something from Sphinx called 'literal include'.
0:38 We will take a look at it in this step.
0:40 And while other static site generators,
0:43 particularly in the javascript space kind of have this bolted on it just never really stays
0:50 working correctly. And I always have to fiddle with it and fork the the library
0:55 or something like that. Whereas with Sphinx,
0:57 this was built in from the start and you can tell because it just works it
1:02 works perfectly. It's what Sphinx was built for and so it's matured has a lot
1:07 of options. Let's take a look at literal include but from markdown.
1:15 So we're talking about including code from a file.
1:17 And Sphinx has the literal include directive.
1:20 If you go to the page documenting it,
1:23 you use the directive pointed at the file name.
1:26 You give it some additional options.
1:29 A lot of these options overlap a lot with the code block directive,
1:33 which makes it really handy to get a lot of the power when you're including like
1:38 a python file or javascript file or something like that.
1:42 So let's take a look at using this.
1:44 I'm back in my project and I've got a python file called my under demo.
1:52 It's here. My_demo.
1:54 It's just a class with a constructor and a method.
1:58 It's got a little bit of doc stringing and it will take a look at that
2:01 a little bit later and we would like to include this code snippet into our markdown
2:07 document into about us. But what we don't really want to do is just keep
2:12 cutting and pasting it and every time it changes,
2:14 we have to remember to go over and cut and paste it back into the markdown
2:18 And we certainly don't want to just type the original version in the markdown.
2:23 Especially if it's part of a library.
2:25 We can't ship the markdown document so we're gonna look at literal include to put this
2:31 into the markdown document. The very simplest way to do this is triple back tick
2:37 code fence. And instead of code block,
2:40 which we just saw, I'm going to say you guessed it literal include and then
2:45 my_demo.py. Very very simple.
2:50 And I'll put a the new line because we're gonna be doing a little bit more
2:54 with this in a second when I save and then head back over to my browser
2:59 and about us. I see that all the code in that python file is now
3:07 included in the document and syntax highlighted exactly as if I cut and pasted it into
3:13 a code block. What if we wanted to pass some arguments to it?
3:18 It works about the way you would expect.
3:22 I could take the sphinx syntax and say emphasize lines 2-3 and save when
3:33 I go back and take a look.
3:35 I see I get some highlighting on this.
3:37 This is something I use all the time to show what changed from one example to
3:42 another when I'm building a file up in multiple parts of a page and just like
3:50 we saw before I can also use this as the Yaml syntax,
3:55 triple ticks and then remove that colon.
4:00 Everything else remains the same. And when I save I'll go back to the browser
4:05 and see that nothing has changed.
4:07 I've just switched over to a different format for providing the options to the literal include
4:15 directive as wrap up. I really really enjoy using literal include especially the options to
4:23 get a fragment from a start pattern to an end pattern instead of having to put
4:29 in line numbers which might change.
4:32 And then all of my examples are highlighted incorrectly or included incorrectly.
4:38 I can put patterns into my code to say pluck this part out or highlight this
4:43 part or whatever it's something I value Sphinx a lot and having a natural syntax in markdown is wonderful.