ReadTheDocs.org (reStructuredText) and Helpinator

ReadTheDocs.org is a cool service for delivering your online documentation to end users. It is based on reStructuredText, a plain text markup language that have a lot in common with Markdown. But, instead of learning yet another markup language to use the power of ReadTheDocs, you can just export all required files in reStructuredText format right from Helpinator.

In this tutorial we will publish Helpinator help file to ReadTheDocs.org.

ReadTheDocs pulls source files from version control systems, and we will use GitHub for this tutorial.

First, register with GitHub if you haven’t done it yet.

Now let’s create a repostitory for our documentation.

Create a new repository

Let’s say we have a documentation folder on our local PC named “C:\Project\help\” . Let’s clone our repository into it. Open command prompt, then change the folder to it and clone the repo:

git clone https://github.com/DmitriPopov/HelpinatorReadTheDocs.git

“HelpinatorReadTheDocs” folder appears in the “C:\Project\Help” folder. It is empty at the moment.

Now srart Helpinator, open the project and click on the lightning icon on the toolbar to open batch compiler. Scroll down the left list to “ReadTheDocs” and double click it to add to the batch. Then select batch item properties accordingly. We are about to write reStructuredText to “C:\Project\Help\HelpinatorReadTheDocs” folder.

Batch compile – ReadTheDocs

When everything is ready click lightning icon on the batch compiler toolbar. Helpinator will generate project files.

Now get back to command prompt, go to” C:\Project\Help\HelpinatorReadTheDocs” folder and run the following git commands:

git add --all
git commit -m "First version"
git push

Upon completion the repo will contain all project files.

Now go to ReadTheDocs.org and register there with your GitHub account, it will allow the service to access your documentation repository seamlessly.

After registration you will be taken to “Import project” screen, click “Import a Project”.

Click “Import project”

ReadTheDocs will ask you to choose a repo with documentation, click “+” sign next to it:

Select a reposiprovidtory to import
Provide project details
In seconds your documentation will be ready

You can then click “View Docs” to view your documentation.

This is what we have as a result: https://helpinatorreadthedocs.readthedocs.io/en/latest/

Leave a comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.