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.