Static Sites with Sphinx and Markdown Transcripts
Chapter: Documenting Code
Lecture: Documenting a Module
0:00 To document a module or even a package. Your starting point is actually in a markdown document.
0:08 This lets you add some narrative text as well as providing a glue point to attach
0:14 the module into the documentation and thus into your site structure we saw previously, how to get auto doc configured for your Sphinx site.
0:27 Let's take a look at the kinds of directives we will use to actually glue code
0:33 into our pages. So the auto doc directive section tells us that there are things such as auto module, auto class,
0:42 auto exception, etcetera. And these let you point at some code that you
0:48 want to be automatically documented and it goes on to show some of the restructured text syntax for how some of this might work.
0:58 But we're in markdown and it's a little bit tricky with MyST and the syntax for
1:04 this, there isn't a direct rapper for getting auto doc expressed in markdown. So what you wind up doing is kind of punting to a raw RST mode where
1:16 you're just embedding restructured text into a directive in the middle of a markdown file. Now you could do and in fact,
1:25 this is what MyST does. You could just leave file like 'Api.rst' in the middle of your markdown project,
1:33 you could have a restructured text file and then plug that into the rest of your
1:39 site. But if you wanted to keep the mark down and just have the directive for the auto doc stuff. This is the way you would do it with eval
1:48 rst. Let's go to the api page where we want to do the work for this. I have a file api.md for markdown and I want to do
1:59 a code fence that has a sphinx directive And in this case I guess it's more like a MyST directive. 'eval-rst'.
2:10 And then the body of this directive is going to be restructured text. So I will write the restructured text version of auto class which is ..autoclass
2:20 And then I'll say the name of the file. This is where the Python path part was important.
2:27 The name of the module and then the name of the class that I want to automatically document and what I'd like to do is pass one argument,
2:38 one configuration option to the documenting of this class members. So now when I save I'll go back to the browser and I don't get anything
2:50 to appear which is a good time for some debugging. I'll head back over to my editor and I see that MyST warned me that I
3:01 put sphinx.ext.autodoc in the wrong place in my conf file. So I'll go fix that in its under MyST enable extensions when really it's supposed to be
3:12 under the sphinx extensions. So now when I save I'll go back to my API file and I'll put a blank line in just to force it to regenerate.
3:26 I don't see any errors. So when I go back to my browser and look at the rendering, I see that it has included my class syntax highlighted,
3:38 and it even has some extra stuff for the structure in it.