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. 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.