Static Sites with Sphinx and Markdown Transcripts
Chapter: Documenting Code
Lecture: Code in a document
0:00 Embedding a code example, into a document is the simplest starting point and is quite
0:07 familiar to markdown folks. In markdown,
0:11 this is known as a 'fenced code block' or more appropriately a code offense.
0:19 And it's triple back ticks some code and some triple back ticks.
0:26 And in when using this in Sphinx it will tap into the underlying 'Pygments' system for detecting
0:34 the language and having some syntax highlighting and there's a little bit more that goes with
0:40 it. When you're using markdown,
0:41 you can have a word after the back text.
0:45 That is the name of the language.
0:55 that argument for the language of the code snippet the code fence.
1:01 Sometimes it has some truly funky ways to pass options for things,
1:06 such as highlighting certain lines. Now in Sphinx,
1:10 a code fence is represented by something called a code block directive and this taps into
1:18 the underlying restructured text system as well.
1:21 It's very similar. It contains code.
1:24 One of the things that's a little bit irritating about it is everything has to be
1:29 indented within that code block to make the block itself.
1:34 But something that is a lot nicer about it is a well defined standard way to
1:41 pass arguments to the code block,
1:45 for example, to show line numbers what line number to start on things like that
1:50 instead of these funky ways that are unique to each system for passing extra information such
1:58 as options. Let's see some code fences in action meaning the markdown syntax to tap
2:07 into the Sphinx code block directive.
2:10 I'll do a very simple one.
2:12 Hello world in Python and I'll do it with the triple back tick for the code
2:17 fence and I will eliminate any language and let it auto detect.
2:24 And so for sphinx and pigments it will be python and I'll write some python code
2:32 that returns an F string saying hello name,
2:40 I'll save this and then go over to the browser and take a look at the
2:45 bottom of the about us page.
2:47 I now have a syntax highlighted and look I misspelled return syntax highlighted chunk of python
2:55 code embedded right in the middle of my markdown file I could make this more explicit
3:02 about what language it is and use the normal markdown code fence syntax for saying the
3:11 language and when I save and go back you'll see that not only have I correctly
3:17 spelled return but nothing has changed.
3:19 It's still thinks this is python.
3:22 Now what if I wanted the equivalent?
3:33 function Hello message and I'll go ahead and put it on multiple lines.
3:41 Now when I save and go over to my about us page I see that I
3:51 We're going to look at passing options,
3:54 which is kind of a MyST thing rather than a markdown thing.
3:59 And for that we're going to kind of turn on the fact that this is a
4:04 code block and use something that we saw previously in our code blocks.
4:10 If it's the code block argument starts with a curly brace,
4:13 then we are telling MyST that this is a directive.
4:18 A Sphinx directive that we're talking to.
4:22 And then the next thing after the directive after the closing of the curly brace is
4:27 the argument to the directive. So I'll save that.
4:31 Go back and you see nothing has changed.
4:33 We're all still good. The previous thing was such a shorthand for that.
4:37 But with this in place I can now do some of the Sphinx and restructured text
4:44 arguments to code block as a directive.
4:47 And so I'll say line numbers as an option and when I save it and go
4:53 back to the browser I see that I now get line numbers added to my code
4:58 block. This is using the Sphinx option syntax with colon,
5:04 colon if you don't like that and you prefer to have YAML,
5:11 we saw this in a previous step of the course I can do triple tick and
5:16 then I can supply YAML and then triple tick again.
5:23 And when I go back to view this in the browser,
5:26 I see that it still works the marriage of markdown syntax for code fences to the
5:32 power of the code block directive in Sphinx works really well because Sphinx has lots of
5:40 powerful options for working with code in your documents,
5:46 things that I use all the time and really make a difference when you're trying to tell a story with code.