Saturday, May 12, 2012

Automate Sphinx - Create rst files automatically from a list of topics

You have lots of topics to document using Sphinx, but bored of creating each .rst file manually? Not to worry at all. Here is a script that will just automate the file-creation task for you. Here we go:

First, download the zip or gz package from

And read the below to get your stuff donne : 

Purpose of the Script
To automate the file-creation process for your Sphinx documentation.  Helpful when you use the "glob" feature in Sphinx, where the tool automatically picks up all the files from the source directory.

If you have a list of topics in your mind(on which you have to create documentation), then just list those topics in a topics.txt file. The script will create the documentaion's rst files. The generated rst files will have some sample content, taken from template.txt file.

Required Software
Python 2.7.x
Sphinx 1.1.x

How to use the Script
You need to first edit/create the following files:

* topics.txt : List down the topics on which you want to write the documentation. The topic will be the title of each rst file.

* template.txt : Include only the common sub-headings. Do not include the title. The title will be taken from the topics.txt.

Once you've done editing the above two files, just run the script. For eg, if you have listed 20 topics in the topics.txt file, then you should see 20 .rst files named based on the topic name. Each of these .rst files will have a title (taken from the topics.txt file), and the sub-headings are taken from the template.txt file.

No comments: