yelp-build: link to pages in another directory?

["A. Jesse Jiryu Davis" <jesse emptysquare net>]

Hi Gnome folk,

I'm taking over a project, the MongoDB C Driver, that Christian Hergert documented in Mallard. It builds with yelp-build. The documentation is split into two directories, one here:

https://github.com/mongodb/libbson/tree/master/doc

And the other here:

https://github.com/mongodb/mongo-c-driver/tree/master/doc

Pages in the latter directory include references to pages in the former. (But not vice versa.) We build each directory with a separate invocation of "yelp-build html <directory>".

THE PROBLEM: when a page in the "mongo-c-driver" directory reference pages in the "libbson" directory, our current build system doesn't make correct HTML links. For example, the "bson_error_t" link here:

http://api.mongodb.org/c/current/mongoc_collection_update.html

... tries to link to a bson_error_t.html page in the *same* directory, instead of to the proper page here:

https://api.mongodb.org/libbson/current/bson_error_t.html

Since the link is wrong, it's a 404, which on our particular server means you're redirected to the home page. People rightly call this a bug in our documentation: https://jira.mongodb.org/browse/CDRIVER-524

I tried just putting the two invocations into a single one:

$ yelp-build html libbson/doc mongo-c-driver/doc

But that munges all the documentation together badly, instead of link from one to the other. Here's the output of that:

http://emptysqua.re/merged-libbson-libmongoc-docs/

How can I tell yelp-build to take a reference from a file in "mongo-c-driver/" to an id in the other directory, like "bson_error_t", and render it as a URL like "../libbson/bson_error_t.html"? Instead of what it does right now, which is render a link to "bson_error_t.html" in the current directory, where no such file exists.

Thanks!

Jesse