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 conf.py 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 my_demo.py
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.