Friday, July 24, 2009

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.

6 comments:

Martin Geisler said...

We've now simplified this so that you only need a standard Docutils installation (version 0.5 is okay). The Makefile searches for both "rst2html" and "rst2html.py" so no symlinking required any more. I hope this helps :-)

Ted said...

I just pulled down from Matt Mackall's "hg" repo, and (as far as I can tell) it looks like it still needs rst2man and rst2html. I'm guessing that eventually those changes will be merged in -- that will be a nice help.

Daniel Steven Lewis said...
This comment has been removed by the author.
Daniel Steven Lewis said...

Path to rst2man.py ain't right

Ted Pavlic said...

@Daniel -- Then it must have changed. Can you provide the updated path here to help others who are building hg from source? Thanks!

Daniel Steven Lewis said...

There's a few copies of it in there. Just search through the extracted directory and choose whichever one you fancy. Same goes for rst2html.py