Migrate away from GitBook

[chrisburr]

At some point we should consider moving from GitBook to something else as the CLI interface we use is no longer maintained and contains various bugs. We could consider moving to CERN GitLab, but this would only apply to the LHCb repositories and we might not want to maintain multiple CI pipelines. I think the preference is to use a "popular" static site generator in the hope that we avoid being stuck with an abandonded tool.

Essential features:

• Full text search
• LaTeX math rendering
• Syntax highlighting
• Collapseable pop outs for challenges or additional details

Potentially desirable features:

• Better support for viewing/downloading code files
• Testing of code snippets (ALICE are already doing this)
• Printable for teachers to use as a reference
• Tempate and CI maintained outside of the documentation repository to allow it to be updated in a single place
• Able to ingest Jupyter notebooks for the Python lessons

[alexpearce]

What are ALICE using?

[chrisburr]

A modified version of our repository, see here.

[alexpearce]

I'm probably blind; where do they test their code snippets?

[chrisburr]

IIRC they parse the sources using building/doc2dock.py looking for snippets tagged with <!-- Dockerfile RUN_INLINE --> (example). This is ran as a daily cron job in Travis.

[henryiii]

MkDocs is visually clean and similar to GitBook, haven't really tested it out yet though. I'm still on the lookout for a Hugo solution; I've seen a few worth testing, and Hugo technically could support the multiple output formats, etc, but haven't found a solution that provides it yet.