Modern Python Projects Transcripts
Chapter: Documentation
Lecture: reStructuredText
Login or
purchase this course
to watch this video and the rest of the course contents.
0:00
In the previous lesson, Sphinx has generated the index.rst file for us. So let's open it. With Sphinx,
0:08
we will be using restructured text to write documentation. Restructured text is similar to mark down, but it has some customs syntax on top of it.
0:17
It's more capable than mark down because it supports installing extensions. And you can, for example, easily link or include other files,
0:24
which is quite important when you're writing technical documentation. If this is the first time you will be using restructure text,
0:31
check out the restructure text primary page from the Sphinx Documentation.
0:36
It will give you a quick overview of how restructure text works and how we can use it. So with VSCode by default
0:43
We get no syntax highlighting. We can't even choose restructure text here, so we'll have to install an extension,
0:51
open extension marketplace and search for restructured text. Okay, this is what we need. That's install it. Now let's go back to our file.
1:08
So now our extension is asking us how to generate the HTML file from the RST files. This is needed. to,
1:16
Get the preview of RST files, so you can see we have this icon here, and when we click it, it will generate the HTML from the RST file.
1:25
So that's like Sphinx because we are using Sphinx. We don't have the preview engines, so we can install it,
1:32
and in the meantime, you can already see that we have the syntax highlighting. So this is a comment. This is the main header of our page.
1:39
Next, we have the table of Content directive, which will generate the table of content from the files that we specify.
1:46
And then we have the content on the main page. In the next lesson, we're going to change this file and add some custom files
1:52
here. If you want to use markdown instead of this restructure text, you can install the recommonmark extension for Sphinx.