Lately I’ve been working on Pintail, a documentation site generator built on top of Mallard, Yelp, and the various other tools we’ve developed over the years. Pintail grew out of the tool that used to build projectmallard.org from Mallard sources. But it’s grown a lot to be able to handle general documentation sites. I want GNOME to be able to use Pintail for its documentation site. I want other projects to be able to use it too.

One of the more compelling features, and something many documentation site generators don’t handle, is that Pintail can pull in different git repositories for different directories. Small projects can get away with having all their docs in one repository. Large projects like GNOME can’t. Here’s a snippet of what the configuration for help.gnome.org might look like:

[/users/gnome-help/stable/]
git_repository = git://git.gnome.org/gnome-user-docs
git_branch = master
git_directory = gnome-help/C/

Pintail’s native format is Mallard, but you can add in support for other formats pretty easily. There’s Docbook support, for example, and I’d like to add AsciiDoc support using asciidoctor-mallard.

There are two major features I hope to have ready soon. Both of them are available as Summer of Code projects. First, documentation sites obviously need search. But it’s not enough to just search the whole site. You want to be able to search within specific documents, or specific versions of documents. I’ve actually already got some indexing code in Pintail using Elasticsearch as a backend.

Second, Pintail needs to be able to handle localizations. I’ve put a lot of work into documentation internationalization over the years. It’s important, and everything I work on will continue to support it. I have some ideas on how this will work.

If you need to build a documentation site, give Pintail a try. I’m building a few sites with it already, but I’d love to get input from people with different needs.

4 Responses to “Build documentation sites with Pintail”

  1. Ben Says:

    Is there a sample hosted somewhere?

    • shaunm Says:

      Not at the moment. It’s something I might work on down the line, but doing a hosted solution involves more than the build tools.

      It is, however, very easy to run on your local machine, even without a web server. You can pass the –local option to pintail, and it will adjust paths and such for local viewing. You can even override any settings for local builds in your config file by putting them in the [local] section.

      • Daniel Espinosa Says:

        If you can run it using Google App Engine, you can create Docker image for custom libraries, as it is. May I can provide you a machine at Google to test it, if you want.

  2. Daniel Espinosa Says:

    I would like to know if are able to produce a website like valadoc.org?

    Even better, actually most API are documented in GIR XML files, get or produce them is easy now a days from sources.

    What do I need to add a manual to help.gnome.org and how do I install in my site?


Comments are closed.