building the-serenity-book locally

[nbarrett]

This is a bit of a basic question but perhaps I'll write out my investigations so far as a logged issue to hopefully help others in future. I'm in the process of contributing to the serenity book but I want to be able to preview the book locally with my pre-committed changes, so I can check for formatting and errors.

I understand that the book uses antora to generate the book as a whole, as the book is written in Asciidoctor. So I think these were the installation steps I eventually needed:

• Checked out the following git repos into my workspace as siblings to each other:
  • https://github.com/serenity-bdd/the-serenity-book.git (this is the book content)
  • https://github.com/serenity-bdd/serenity-docs.git (this is the book assembly tool)
• Installed (at least) node version 8
  • nvm install 8
  • nvm use 8
• globally installed asciidoctor and antora:
  • brew install asciidoctor
  • npm i -g @antora/cli
• from the-serenity-book git directory:
  • npm i @antora/site-generator-default
• from serenity-docs git directory:
  • npm i @antora/site-generator-default

Then I set to work on the content by making adoc changes locally in the-serenity-book project:

• modules/ROOT/assets/images
• modules/ROOT/pages/
• modules/ROOT/examples/

Then I tried to build it locally:

• ran this command in the-serenity-book directory to generate content into the build folder:
  • asciidoctor modules/ROOT/pages/*.adoc -D build -a imagesdir=assets/images
• temporarily edited url property in serenity-docs project site.yml to point to my local project as follows:

site:
  title: The Serenity BDD Book
content:
  sources:
#  - url: https://github.com/serenity-bdd/the-serenity-book.git
   - url: ../the-serenity-book
#    branches: master
ui:
  bundle:
    # url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable
    url: themes/serenity-antora-theme.zip
    snapshot: true

runtime:
  pull: true

• ran the command in the serenity-docs project as follows:
  • antora site.yml

But the content output to serenity-docs/build/site/theserenitybook/0.1.0 is still not the up to date content!

Please can you point out the error of my ways? Oddly enough my recent PRs #5 and #4 found their way successfully to the published output, so this is just a local build problem I'm having 😞

[cliviu]

Hi @nbarrett . It should be correct. I have noticed that I do not have runtime: pull: true part in the site.yml