Plan for eventually adding testable tutorial-style docs to Hg

Peter Arrenbrecht peter.arrenbrecht at gmail.com
Sun Feb 7 03:32:54 CST 2010


Some of us at the sprint have been discussing ways to integrate
tutorial-style documentation into Hg directly. We could then generate
version-specific static HTML for this to include with distributions,
much like the man pages. And we could make the examples in the
documentation testable (doctest-style), as I already do for pbranch.
This is not going to happen right now, but we might want to do it once
an extension with such docs should be promoted to an official
extension.

The plan is to

 * use RST to write the docs because we already use RST for the man pages,
 * keep the source for these pages in the main Hg repo,
 * use Sphinx to produce the static HTML pages,
 * use a layout that resembles the one at http://mercurial.selenic.com/,
 * use something like pbranch uses today to run embedded sh-based tests
   (http://bitbucket.org/parren/hg-pbranch/src/tip/tut/docbash.py),
 * maybe have a separate mailing list for things related to docs only,
 * maybe have option to edit a page directly on the web, which sends a
patch to the correct list, and
 * not consider internationalization for the moment.

We also considered using an Hg-based wiki like Hatta for this, but
decided in favor of statically produced pages in the end.

Examples of such docs:

  http://sjl.bitbucket.org/hg-prompt/
  http://www.arrenbrecht.ch/mercurial/pbranch/index.htm

and maybe also

  http://mercurial.selenic.com/guide/
  http://mercurial.selenic.com/wiki/Tutorial

-parren


More information about the Mercurial-devel mailing list