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.