Set up GitHub Actions to automatically build gitbook

[dtolnay]

Currently I need to update both the markdown source and the generated html. I should be able to push changes to markdown and have GitHub Actions push a commit containing built html.

[indiv0]

If you're still interested in pursuing this, I've got it working for the rusoto GitBook: https://github.com/rusoto/rusoto.github.io.

I believe you'll need to do the following:

1. Copy the publish.sh, package.json, .travis.yml
2. Modify publish.sh to refer to the correct branches (we use master and source), as well as the correct git user.
3. Modify package.json to refer to serde and not rusoto
4. Generate a GitHub token with public_repo access, encrypt it, and put it into the .travis.yml.
5. Re-organize the directory a little (our book.json and publish.sh assume the book's source is in src/.

BTW thanks for making a serde GitBook! I've used the layout as the basis for ours :)

[sta-szek]

Recently, I was facing same problem.
My solution (java + gradle + travis + gitbook) is: https://github.com/sta-szek/pojo-tester/blob/master/deployPages.sh

[MCOfficer]

Hello,

I looked into this, and it seems simple enough (using actions instead of travis). However, i'm quite confused when it comes to the structure of this repo.

How is the book regenerated? Currently i'm using gitbook build, but that builds into the the _gitbook folder, and produces different html than the one in the root.
Which html is actually the correct one? The html in _gitbook is gitignored.

[dtolnay]

How is the book regenerated?

Here is what I run in the repo root to regenerate:

$ gitbook build && rm -rf gitbook styles && mv _book/* .

This is with these version of gitbook locally, which might be old. If a newer gitbook is generating different html then it's probably fine to use the new one.

$ gitbook --version
CLI version: 2.3.2
GitBook version: 3.2.3

serde-rs.github.io/index.html

Line 10 in 40f70d8

<meta name="generator" content="GitBook 3.2.3">

[MCOfficer]

I see. 3.2.3 is the exact version the workflow is using.

There's a slight problem, though, gitbook seems to make changes based on the time whenever you run gitbook build (those we're all the changes i was seeing, apart from that it's the same html):
d7883b6

That sucks, it would mean a new commit whenever this workflow runs. Is there a way to prevent this?

[dtolnay]

We could run a sed to normalize the timestamp to some permanent fixed one.

It may be worth looking into how this timestamp gets used from the gitbook codebase; if it's totally superfluous they may accept a PR with a configuration option to disable it. Alternatively I think gitbook's plugin system has an html postprocessing step so we could write a plugin that strips it.

[MCOfficer]

yikes. i will have a look, but seeing how gitbook (at least the version we're using) is in maintenance mode, it might be worth to just do #17 instead...

Edit: Looking at the git history, we might just take that. most commits are changes to the book anyways.

[MCOfficer]

I'm not exactly proud of it, but here's one solution:

gitbook build
rm -rf gitbook styles
mv _book/* .
git restore gitbook/gitbook-plugin-lunr/search-lunr.js # don't revert https://github.com/serde-rs/serde-rs.github.io/commit/1fd8104d5a16256279831dc90cb8f7a61b26ec58
if ! git diff -U0 ':!search_index.json'  | grep -P '^[+-](?!\+\+)(?!--)' | grep -v -P '[+-]\s+gitbook\.page\.hasChanged'; then # Check if we have any diff *other* than search_index.json and lines starting with gitbook.page.hasChanged (which are just metadata)
  echo No content changes, resetting to prevent a commit
  git reset --hard 
fi

Tests:

Commit without content changes aborts.
Commit with changes produces MCOfficer@3b295d2