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.

Talk Python's Mastodon Michael Kennedy's Mastodon