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 a single file. But what about a code base?
0:11 Sphinx is basically built for that to make the documentation for all of Python itself. In fact, how does that look?
0:19 But in a markdown site this brings up the centerpiece of the Sphinx ecosystem. Auto dock with auto doc. You point a sphinx document at your code and it
0:33 generates kind of a structured highlighted interlinked collection of sections and even better the symbols in
0:42 your code, whether it's Python or whatever become roles in Sphinx, which you can directly linked to from narrative documentation.
0:53 Let's set up auto doc for use in our MyST powered markdown website. First in our conf.py file, which is where we set up Sphinx.
1:04 We need to turn on auto doc. It's an extension that's bundled with Sphinx but not turned on by default. So I'll say sphinx.ext.autodoc.
1:15 And with that extension enabled, I also need to make sure that the code for my project my my_demo.py file is available in Python path.
1:29 So I'll do this kind of trick where I import sys in list and add dot the current directory to the Python path,
1:38 which will then let me point auto doc at a module. So that's all it takes to get auto doc set up. In fact, the Python part really isn't needed.
1:50 It's only if you're not working in kind of an editable installed Python package if you're just doing kind of a one off app or something like that.
1:59 So it's not that much work. And once you get started, we can take in the next step a look at
2:06 bringing documentation of modules and packages into your documentation.