On Fri, Dec 03, 2021 at 03:57:41PM +0100, Ævar Arnfjörð Bjarmason wrote:
> > One caution that springs to mind is that there may be external tooling
> > which processes these documentation files directly, and such a change
> > might break them. (The one which popped to mind immediately was the
> > git-scm.{org,com} website, though I don't know what their tooling
> > looks like.)
>
> True, I hadn't looked into how that worked before, but behold!
> https://github.com/git/git-scm.com/blob/main/lib/tasks/index.rake
>
> It seems to be a re-implementation of a non-trivial part of the doc
> building process.
Yeah. It's kind of ugly, but the complication there is that the docs are
updated on a running heroku dyno which does not actually have a clone of
the new version of Git, let alone an actual build.
It's also hard for it to just use the output of our "make" anyway, since
there's some munging that happens to fit the page content inside the
rest of the site, changing links, etc. We could in theory operate on the
result of "make html" more directly, but it would definitely require
some changes.
IMHO the way the site operates now (with "live" updates by extracting
content from git.git and shoving it into a database) is not ideal. It's
not like we're importing new Git versions once per minute. It would be
easier to reason about as a "static site" which is built by a process
which actually has a clone of git.git and invokes "make html" there,
post-processes the pages, and saves the whole thing as a Git tree. And
then run that build occasionally (at new releases, or changes to the
source, but also periodically via GitHub Actions or similar to pick up
changed book content). It's just a big enough change (and there are some
gotcha around things like site search) that I've never gotten around to
it.
-Peff
