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.