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.