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