Static Sites with Sphinx and Markdown Transcripts
Chapter: More Authoring
Lecture: TOC: Table of Contents
Login or
purchase this course
to watch this video and the rest of the course contents.
0:00
With Sphinx. It isn't enough to just leave a file in a directory. You need to include it in what Sphinx calls a 'Table of Contents'.
0:11
So let's take a look at the toctree directive, then explain what's going on behind the scenes and then explain why you should care.
0:22
Here is the Sphinx documentation page for the toctree directive and it explains a little bit more about the purpose of it.
0:32
The purpose is to link files most of the time in a directory in a particular
0:38
order, including and excluding what you want to go into the generated output. And you can see some of the options that are included with it.
0:49
You can add things such as captions and names and globs and we're gonna go over a couple of these back in our 'index.md' file.
1:01
We already have a toctree director of that. We converted to the Myst Markdown syntax in a previous step.
1:10
It is done as a code fence with the triple back tick. And then since the first argument of the code fences in a curly bracket,
1:20
that means it's a tapping directly into a sphinx directive. The toctree directive, we're passing to configuration options to the directive.
1:31
We're going to set how deep to go in the table of contents. And what this does is each entry in the table of contents has headings and sub
1:40
headings and subheadings and all of those can be plucked out and inserted into the hierarchy of the table of contents.
1:49
So you could jump directly to a heading from the table of contents and then the
1:54
second one we're using is a caption where we set the information for the caption, we put it in quotes because there's a colon that we wanted to have.
2:03
Then we have a blank space and then we have a listing of items that are supposed to go into this table of contents.
2:12
These are paths, they can have relative and absolute slashes and dot thoughts and things in front of them and order matters.
2:25
The entry that you put these is the entry is the order that they will appear in the rendered output. It also has some kind of semantic meeting as well.
2:36
So briefly if we wanted to change the caption that was displayed, we could edit this if we didn't want to manually list everything in a very large
2:47
directory if order didn't matter if we want a convenience over meaning and structure or something
2:53
there is a glob that is supported so I could put as an option to turn on globing and then here just say asterisk or some kind of glob
3:05
character and I could have multiple lines on this to do different kinds of things for
3:09
this. What if we didn't like the syntax that was the syntax for these options This restructured text, what we want to YAML,
3:22
MyST supports, YAML to send configuration arguments to directives and it would look like this kinda like front matter in markdown documents.
3:32
It's a triple dash and then a pile of YAML and another triple dash and a blank line and then everything else is the body.
3:41
So in this case we've basically converted key value pairs from the restructured text syntax into key value pairs for YAML now is wrap up.
3:55
Why do we care about table of contents? Why do all this extra work?
3:58
Well Sphinx is about structure more than how it looks because it renders to multiple kinds
4:04
of outputs and it has a lot of cool facilities for linking and structure and all
4:11
that kind of stuff and so it cares about structure within a document but also between documents and that's where the toctree comes in play.
4:20
You can have a toctree to a range of information hierarchy. You can even have multiple toctrees in the same document.