Installing docutils for Mercurial (rst2man and rst2html)

If you're building Mercurial from its source, you might notice that the latest versions are using reStructuredText to markup their documentation. Hence, you'll need to install docutils. Additionally:

• You'll have to install the rst2man tool that is presently only available in the docutils "Sandbox," which you have to download separately.
• You'll have to make sure you have the new rst2man.py tool accessible in your PATH as rst2man.
• You'll have to make sure you have the included rst2html.py tool accessible in your PATH as rst2html.

So it's no surprise that yet-another-Python-related-adventure is yet-another-Python-related-headache. Here's how to get up and running. Things should get substantially simpler if and when docutils starts including rst2man as part of their standard distribution (however, you'll probably still have to make the simlinks unless Mercurial's installer is able to call the rst scripts with their .py extension). Meanwhile, here are some steps that will hopefully get you (the UNIX or Mac/OS X user) moving in the right direction.

• First, go to the docutils website and download the docutils snapshot as well as the docutils sandbox snapshot.
• tar zxf those tarballs to extract the docutils source code. That should give docutils and sandbox directories.
• Copy sandbox/manpage-writer/tools/rst2man.py to somewhere in your PATH (e.g., /usr/local/bin/rst2man.py or ~/bin/rst2man.py if you have ~/bin in your PATH).
• Create a symbolic link in your PATH from the rst2man.py you just placed there to rst2man. For example, symlink /usr/local/bin/rst2man.py to /usr/local/bin/rst2man by doing ln -s rst2man.py rst2man in the /usr/local/bin directory.
• Copy sandbox/manpage-writer/docutils/writers/manpage.py to docutils/docutils/writers/manpage.py.
• In the docutils directory, run python setup.py install (for a global installation) or python setup.py install --home ~ (for a home installation).
• Copy docutils/rst2html.py to somewhere in your PATH (e.g., /usr/local/bin/rst2html.py or ~/bin/rst2html.py).
• Create a symbolic link in your PATH from the rst2html.py you just placed there to rst2html. For example, ln -s rst2html.py rst2html inside your /usr/local/bin or ~/bin directory.
• Fetch the latest version of Mercurial and build it. Assuming you have all of the other dependencies, it should build OK.

Of course, YMMV, but I hope that at least helps get you on your way.