Learn how to include links and content from different files to your documentation. This lesson will also cover how to render and preview the documentation before building using an online tool.
Previewing ReStructuredText (.rst) Files
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…
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.
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.
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: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.
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.
Become a Member to join the conversation.