Join us and get access to thousands of tutorials and a community of expert Pythonistas.

Unlock This Lesson

This lesson is for members only. Join us and get access to thousands of tutorials and a community of expert Pythonistas.

Unlock This Lesson

Hint: You can adjust the default video playback speed in your account settings.
Hint: You can set your subtitle preferences in your account settings.
Sorry! Looks like there’s an issue with video playback 🙁 This might be due to a temporary outage or because of a configuration issue with your browser. Please see our video player troubleshooting guide to resolve the issue.

Configuring Sphinx Subheadings With :maxdepth:

Learn how to configure subheadings and nesting depth in Sphinx using :max depth:

00:00 One last word on maxdepth. Another thing that maxdepth allows you to do is to have subheadings in your table of contents. I went ahead and changed our maxdepth to 3.

00:09 What this allows us to do is to show subheadings inside particular files. So in our help file, we have a main title called Need Help, and we’re going to have a subtitle going Need further help.

00:23 And we’re going to simply create this as a subtitle, which that is the syntax—or, a subsection, which is the syntax in RST. We’re going to go Please join our IRC channel on freenode under doctut.

00:43 And once we write this file… And I’ll quickly show you how our index.rst looks. I’ve changed the maxdepth to 3, and that’ll render three levels deep into our structure. So for example, our structure before was two levels deep.

00:57 We had a main title and that’s all we had. Now we have a main title, subtitle. It should allow us to render both sets of documentation. I believe even with two, this should render properly.

01:09 Let’s take a look at that first. Let’s go ahead and build our source. We’re going to go make html. Okay.

01:18 And we’re going to open build/html/index.html. And as you can see, we see our nested Need further help. So as you can see, our Need Help is our main one, and Need further help has been nested inside that, which is inside our help.rst file.

01:35 We also showed that our nesting depth of two is more than enough.

01:40 So, now that we have all this set up and we understand how to structure our documentation, how do we get this hooked up to Read the Docs?

Become a Member to join the conversation.