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

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