Allow building out-of-tree
ISSOtm opened this issue · comments
This was requested by @mid-kid, who packages Pan Docs as a Gentoo package for offline viewing. Currently, this chokes by default because we expect to be able to call git show to retrieve the commit info for the front page.
To do:
- Figure out what to display on the front page when building out-of-tree
- Decide on an interface to enable out-of-tree builds
- Figure out a good place to document that last item
For the second bullet, I think we can rely on a key in mdBook's output.pandocs table, which would disable Git scanning if set to true. This can even be configured via environment variables e.g. MDBOOK_output__pandocs__out_of_tree=true mdbook build to avoid patching the sources.
For the last item, I think DEPLOY.md is the best place?
The third item is very quickly gonna be noticed by simply the build failing. I don't think you need to do much more with regards to that, other than either making a descriptive error, or expecting the builder to dig into the code for it (as I did, long enough to know that it wasn't gonna be a simple sed :))
That special configuration is needed can be made obvious, sure; however, that the option exists at all may be less so! It seems likely to me that a packager will sooner reach for patch -p0 than digging through the configuration.
Then there's the issue of detection; I'd assume that ".git does not exist" should be the correct basis, but maybe I'm missing something?
Additionally, you remarked via IM that we ought to pass the --git-dir argument to git show to ensure that we don't accidentally pick up a parent Git dir. (I'm not sure if that plays nice with submodules, but my intuition says that it should.)
As for the patch, well, I think patch is indeed more appropriate than sed, yes :P
But you will have to update that patch now that #513 has landed.