Static Sites with Sphinx and Markdown Transcripts
Chapter: Documenting Code
Lecture: Code in a document

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

Talk Python's Mastodon Michael Kennedy's Mastodon