Jupyter-book: Provide and document template .gitlab-ci.yml for easy deployment on GitLab

[eburling]

For us wayward souls that have migrated to GitLab, it would be great to have some documentation on how to effectively deploy books there, i.e. a boilerplate .gitlab-ci.yml file would be most beneficial.

Cheers!

[choldgraf]

This sounds like it would indeed be useful! Unfortunately I have no experience with GitLab - if somebody wants to give a shot at this I'm happy to review PRs and/or give it a shot!

[nthiery]

FWITW, here is an example; first stage build a docker image with all the required tooling. Second stage builds the book itself.

https://gitlab.u-psud.fr/nicolas.thiery/ter-jupyter/blob/master/.gitlab-ci.yml

[bsamadi]

You can see my example here:

https://hackmd.io/@mechatronics3d/S1lfojdjL

[nthiery]

Thanks @bsamadi for sharing!

Did you manage to make the binder / thebelab / ... links and such work with gitlab?

[bsamadi]

You're most welcome. I have used binder with GitHub. I am still not sure what Thebe Lab is. I just saw it yesterday. I will give them a try on Gitlab.

[nthiery]

Ok! Just to clarify if needed: binder and thebelab by themselves work well with gitlab; what I haven't found from reading jupyterbook's doc is whether and how it's currently possible to configure it to enable the binder/thebelab links . The configuration seems quite github oriented.

[choldgraf]

@nthiery mostly that's just because I am not super familiar with GitLab or how to configure Thebelab for it...so PRs in Jupyter Book are welcome!

[nthiery]

@nthiery mostly that's just because I am not super familiar with GitLab or how to configure Thebelab for it...so PRs in Jupyter Book are welcome!

Ok, thanks for feedback! I'll dig into the code. If you have a quick
pointer for where the binder / thebelab URL are computed, that's
welcome.

[choldgraf]

Binder links are actually configured with the sphinx-book-theme: https://sphinx-book-theme.readthedocs.io/en/latest/launch.html

This is probably the function where this is configurable: https://github.com/executablebooks/sphinx-book-theme/blob/master/sphinx_book_theme/launch.py#L24

I actually wasn't sure if Thebelab was planned on continuing to be maintained / developed. There have been a few PRs that didn't get much attention lately, and I was wondering if there were plans to sunset it, but I guess that is not the case?

[nthiery]

Ah ah, I see now why my couple greps had given no hints; it's handled
by another project. Makes sense. Thanks for the links!

I actually wasn't sure if Thebelab was planned on continuing to be
maintained / developed. There have been a few PRs that didn't get
much attention lately, and I was wondering if there were plans to
sunset it, but I guess that is not the case?

It's so useful that I sincerely hope it will live and strive (or be
superseded by another project)! But indeed, there is a lack of
maintainer manpower these days. Not sure how to proceed there. It's
too deep in the javascript world for me to be competent.

[choldgraf]

@nthiery let me know if I can help point you in the right direction!

and agreed re: the usefulness of Thebelab. I think Jupyter Book certainly benefits from it, as well as Binder. I've tried to help out with the project though I'm not very well-skilled in Jupyter Lab or javascript. Maybe worth having a short meeting to try and plan a strategy to keep it sustainable?

[TomasBeuzen]

A .gitlab-ci.yml file was just recently merged with the jupyter book cookiecutter which leverages @bsamadi's example (will add you to acknowledgements in the repo), give it a try with:

jupyter-book create --cookiecutter

GitLab support in the CC is still a WIP but this is a start.

[chrisjsewell]

Thanks @TomasBeuzen

[choldgraf]

beautiful, thanks @TomasBeuzen - we should refer to this file in the jupyter-book docs somewhere 👍