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.
0:04 So let's open it. With Sphinx,
0:07 we will be using restructured text to write documentation.
0:10 Restructured text is similar to mark down,
0:13 but it has some customs syntax on top of it.
0:16 It's more capable than mark down because it supports installing extensions.
0:20 And you can, for example,
0:21 easily link or include other files,
0:23 which is quite important when you're writing technical documentation.
0:27 If this is the first time you will be using restructure text,
0:30 check out the restructure text primary page from the Sphinx Documentation.
0:35 It will give you a quick overview of how restructure text works and how we can
0:39 use it. So with VSCode by default
0:42 We get no syntax highlighting. We can't even choose restructure text here,
0:47 so we'll have to install an extension,
0:50 open extension marketplace and search for restructured text.
1:01 Okay, this is what we need.
1:02 That's install it. Now let's go back to our file.
1:07 So now our extension is asking us how to generate the HTML file from the RST
1:12 files. This is needed. to,
1:15 Get the preview of RST files, so you can see we have this icon here,
1:19 and when we click it, it will generate the HTML from the RST file.
1:24 So that's like Sphinx because we are using Sphinx.
1:27 We don't have the preview engines, so we can install it,
1:31 and in the meantime, you can already see that we have the syntax highlighting.
1:34 So this is a comment. This is the main header of our page.
1:38 Next, we have the table of Content directive,
1:40 which will generate the table of content from the files that we specify.
1:45 And then we have the content on the main page.
1:48 In the next lesson, we're going to change this file and add some custom files
1:51 here. If you want to use markdown instead of this restructure text,
1:55 you can install the recommonmark extension for Sphinx.