Previewing ReStructuredText (.rst) Files

00:00 Now that we’ve done that, let’s go ahead and build our text here. I’ve gone ahead and filled in our license.rst files as well. If you try to build the project without any headers, like a title heading, Sphinx will spit out saying, “We’re going to skip over them, we’re not going to render any title headings for this particular file because there’s no titles.” So, the way the documentation and the maxdepth works is that it requires you to have some type of header. So in this case, we have a License header. We can give it another Contact space here for somebody to contact in case they’re interested about licenses. So we’re going to say something like Questions? Please contact…

00:45 Now that we have that, we have two headings and in our help.html I’ve simply said if you have any trouble with the project, please email blah.

00:54 So we have sections and our headings. Once we’ve done all that, we should be able to generate our documentation by the same process as before. We’re in the same directory as our Makefile, so we’re going to go back up one.

01:05 We’re going to go make html.

01:09 It builded all of our documentation without much of an issue, and next, we’re going to open up our documentation. So we’re going to go open build/html/index.html, and that is the root. So as you can see, we have our title.

01:24 We have another simple header. We have a code block. We have our license directory, which renders all of our stuff. If you want to have any contact information, please go here.

01:32 We have our contact information. We have our help in the next topic. As you can see, it tells you to email. The documentation, we have our versioning. And there you have it.

01:40 You have a full set of documentation that you’re building locally as you develop your stuff. So, the process goes as follows. You go to your root RST file, which in our case is the index.rst.

01:56 You add your sections under :maxdepth:. Please be sure to place the beginning of your filename under the first colon in the :maxdepth: line.

02:05 If you space this to the left, Sphinx won’t be able to find the RST file that you’re looking for. This is crucial and causes many, many people to get frustrated when first trying to render multiple pages with Sphinx. To have your toctree is required by Sphinx, so you must have this regardless of whether or not you put anything in there.

02:25 And that is the flow for adding more files, and then you simply create new headings and new files. Those of you who want to have some type of tool to help you render, I would highly recommend Socrates. So if you take a look at our…

02:38 We’ll simply pbcopy our license.rst, so we’re going to cat our license.rst. And we’re going to go pipe that to pbcopy.

02:49 And we’re going to paste it into our Socrates file. So as you can see, it renders everything as you would in RST. So you have our actual RST, and this is what a rendered format of this RST would look like.

03:01 So if you’re looking to have something in more real time, you can edit all your RST files in here and then paste them into the corresponding file. Things like toctree and Sphinx-specific stuff will not work here—only pure RST syntax.