Reading Django documentation with restview

Question

I am using Fedora 18 on Virtual Box on my Windows XP desktop to learn Django. After going through the .txt documentation files, I discovered these files were written using restructuredText. I've been spending the last day or so trying to figure out how to convert the files into something readable (HTML, Latex, PDF, etc.). First thing I did, was install docutils (from source - download page) and used rst2html.py to convert the files to HTML to be readable.

When I used this tool, I was getting the Unknown interpreted text role "doc", Unknown interpreted text role "ref", Unknown interpreted text role "term" errors, and more when opening the docs/intro/index.txt, docs/intro/install.txt and docs/intro/tutorial01.txt files. I was able to find very little on Google describing the exact problem I was having so I tried to use a different option.

Naively thinking the errors were native to docutils I decided to search for another tool and found this page and installed restview. Well, I didn't realize restview used docutils so I ended up back at square one.

How do I get rid of these and other errors? Did I install docutils and restview correctly?

Please tell me if I need to add more info

Answer 1

You need to use Sphinx. This tool is used by the Django project and it defines additional reStructuredText constructs to complement those defined by docutils. Such as

• http://sphinx-doc.org/markup/inline.html#role-doc
• http://sphinx-doc.org/markup/inline.html#role-ref
• http://sphinx-doc.org/markup/inline.html#role-term