Static Sites with Sphinx and Markdown Transcripts
Chapter: Documenting Code
Lecture: Configuring autodoc

Login or purchase this course to watch this video and the rest of the course contents.
0:00 We've looked at code snippets directly in a markdown document as well as including code from
0:06 a single file. But what about a code base?
0:10 Sphinx is basically built for that to make the documentation for all of python itself.
0:16 In fact, how does that look?
0:18 But in a markdown site this brings up the centerpiece of the Sphinx ecosystem.
0:25 Auto dock with auto doc. You point a sphinx document at your code and it
0:32 generates kind of a structured highlighted interlinked collection of sections and even better the symbols in
0:41 your code, whether it's python or whatever become roles in Sphinx,
0:47 which you can directly linked to from narrative documentation.
0:52 Let's set up auto doc for use in our MyST powered markdown website.
0:59 First in our file,
1:01 which is where we set up Sphinx.
1:03 We need to turn on auto doc.
1:06 It's an extension that's bundled with Sphinx but not turned on by default.
1:10 So I'll say sphinx.ext.autodoc.
1:14 And with that extension enabled,
1:17 I also need to make sure that the code for my project my
1:24 file is available in python path.
1:28 So I'll do this kind of trick where I import sys in list and add dot
1:34 the current directory to the python path,
1:37 which will then let me point auto doc at a module.
1:42 So that's all it takes to get auto doc set up.
1:46 In fact, the python part really isn't needed.
1:49 It's only if you're not working in kind of an editable installed python package if you're
1:55 just doing kind of a one off app or something like that.
1:58 So it's not that much work.
1:59 And once you get started, we can take in the next step a look at
2:05 bringing documentation of modules and packages into your documentation.