Learn how to make changes to your Sphinx documentation. You’ll see how to format .rst files to add sections, headers, table of contents, and code blocks.
Join us and get access to thousands of tutorials and a community of expert Pythonistas.
This lesson is for members only. Join us and get access to thousands of tutorials and a community of expert Pythonistas.
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 refer to our video player troubleshooting guide for assistance.
Updating Your Sphinx Documentation
00:00
Now that we’re successfully able to build our documentation, let’s go ahead and take a look at our documentation and make some changes. So, we’re going to open up our index.rst in VIM. As you can see, this simply contains the same amount of code or text that was in our rendered version, in our HTML version.
00:18 So, we can go ahead and delete this comment up here. And those of you who aren’t familiar with RST syntax, I will recommend a rendering tool that allows you to get up to speed really quickly. Let’s quickly change this line and let’s go ahead and name our documentation title something else.
00:38
So let’s call it Simple Documentation Tutorial: Doctut.
00:51
Excellent. So that we’ve made a change, we’re going to go ahead and save it. And then we’re going to go ahead and build our code again. So we’re going to go back to the Makefile directory. We’re going to go make html, and we’re going to open build/html/index.html.
01:08 And as you can see, our title changed and we’ve successfully changed a piece of our documentation. So, let’s go ahead and quickly add another section to our documentation.
01:18
This requires us to go back into this file, our RST file. So, we’re going to go into our source/ directory. We’re going to go vim index.rst. We’re going to create another title section.
01:30
Let’s call our section Guide right here.
01:35
Instead of Contents, we’ll call this Guide.
01:42
And this will give us a section title called Guide, which we will then put under the sections of our documentation. So, let’s have a few sections under here. And in order to do the sections, what you want to do is get it under the maxdepth of 2.
01:56
Now, this :maxdepth: will tell Sphinx how many title sections to render in the table of contents. So, let’s say we have a file called license and a file called help.
02:12
When we build next time, what Sphinx will do, it will go and look for those files in saying, “Hey, where is our license.rst and our help.rst?” And it’ll render all those particular pieces and create a table of contents under our guide.
02:24
Let’s create one more other section here, just for help’s sake. We’re going to go Another simple header.
02:39
Here is some text explaining some very complicated stuff.
02:48
And then what we’re going to do after that, we’re going to create a code block, and that’s done fairly easily. We’re going to indent four spaces, and then we’re going to go print 'hello'.
Bartosz Zaczyński RP Team on Nov. 23, 2020
@Pierre You can take advantage of the online editor provided by GitHub gists, which supports reStructuredText syntax.
Pierre on Nov. 23, 2020
Oh wow! What a great tool. Thanks, @Bartosz!
Become a Member to join the conversation.
Pierre on Nov. 20, 2020
Hi Mahdi,
You suggested a rendering tool to help those unfamiliar with the reStructuredText markup language syntax to “get up to speed quickly”. Can you recommend one? I code in Vim (if that’s relevant).
Thanks, Pierre