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. 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:41
And while other static site generators, particularly in the javascript space kind of have this bolted on it just never really stays
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:39
a Python file or javascript file or something like that. So let's take a look at using this.
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.