The-turing-way: [case study] improving build docs and reproducibility of the turing way book

[kkmann]

tl;dr

The Turing Way (TTW)has reached a substantial level of complexity now and building the book is not necessarily trivial (see also #1187); we should improve documentation and use methods from the Guide to RR to offer different approaches for reproducing the Turing Way (as in: build it from sources).

What needs to be done?

• [ ] provide conda environment for building the turing way (the official contributing guide links to virtual environments which are not even covered in TTW) (not possible due to some packages not being available on conda)
• [ ] specify build environment in a repo2docker compatible way in .binder edit: not necessary, just use specs in book/website (although that is a bit of an odd location); should be updated to conda environment to for consistency with the first item (see above)
• [ ] [maybe later] set up CI/CD to automatically build and push a new docker container every time .binder changes
• [ ] describe how to build TTW using that container (can we put a bash script somewhere so that it really boils down to docker exec *containername* bash build-ttw.sh) r2d
• [x] make sure the book can be build using a Binder link to mybinder.org
• [ ] document all the different ways of reproducing TTW in the new chapter in RR examples, see #1242
• [ ] update the contributing guidelines to point to the online version of the Turing Way and the example. Depending on their skill level people should then be able to learn the respective techniques from the RR guide and tart building.

Who can help?

• [x] @kkmann for integration with #1242 and testing
• [ ] anyone for testing and checking that the docs are actually sufficient to get things working, you could say: the less you know about coding the better!

---

Updates

• jupyter-book and datascience are not available via conda. change of plans: we will not be able to use a conda environment to build the book; should probably discuss that point in the 'case study' (conda/limitations).

[sgibson91]

What's the use case for building it from source? There was also a discussion in https://github.com/alan-turing-institute/the-turing-way/pull/1017#issuecomment-611598463 when we upgraded the Jupyter Book to use the beta version (with a Sphinx backend instead of Ruby, which weakened our dependency on Docker). Why do we need a binder environment when Netlify does this for us? @malvikasharan what are your thoughts?

[kkmann]

The use case is two-fold:

1. make it easier to build the book for new contributors
2. by implementing different strategies, we can showcase the methods described in the Guide to RR (effectivly making TTW self-documenting).

[sgibson91]

1. make it easier to build the book for new contributors

Why do new contributors need to build the book as opposed to the workflow of:

• create new branch
• create commit on new branch
• open PR
• use Netlify's preview feature?

I think building the book is advanced. I've only ever done it as part of the upgrading the Jupyter Book version. I'm really interested in understanding why this pathway is being chosen rather than using the infrastructure already in place?

Also, see the following action for repo2docker stuff https://github.com/marketplace/actions/repo2docker-action

I'm also not convinced that Jupyter Book will launch in a binder (I don't think Binder "knows" about the Jupyter Book UI), and rather it's supposed to work the other way round. As in, we (hypothetically) have interactive pages of the book and the compute is provided by mybinder.org, https://jupyterbook.org/interactive/launchbuttons.html#binder-buttons-for-your-pages (@choldgraf?)

[kkmann]

Building locally is a lot quicker. Also, shouldn't we have the ambition to practice as we preach? If TTW was only about simplicity, we should probably use a google doc instead of Jupyter book in the first place x)

Concerning mybinder.org: jupyter-book build gives me a static index.html that I can open. At least the non-interactive stuff (everything at the moment) should work then. Anyhow, the mybinder.org workflow is more eyecandy since it would not speed things up in any way (to the contrary). If we use repo2docker it would be just be nice to showcase the possibility, if it works, otherwise ignore it.

[sgibson91]

I think if we want mybinder.org "eye candy", I'd rather get some interactive examples in the book than put effort into building it in a binder instance. That feels like it adds more value in terms of engaging with the content than being able to build the book in a binder environment, where any changes are lost as soon as your browser closes.

[sgibson91]

Here's what I'd like to see in the contributing guidelines in terms of developing locally:

1) Recommended local development route. This should be accessible to _everyone_. We have contributors who are completely new to GitHub/Markdown/the whole concept, and so this pathway should include them even if it's slower.
2) Advanced super user route. This can be a docker container for those who choose it and know what they're doing.

[kkmann]

I guess my point is that is would be cool and conistent to have the various build processes for TTW documented in the book itself and then just link that section instead of duplicating it in the contributing guidelines.
In that way we benefit from any updates to the core book automatically and get another nice example for hoe to do these things in practice ;)

edit:
Also, you dont need to be a superuser to build using a container. You can just use singularity to execute jupyter-book build . in the docker container. Takes a bit longer the first time but works like a charm as long as you only execute shell commands x)

[sgibson91]

I guess my point is that is would be cool and conistent to have the various build processes for TTW documented in the book itself and then just link that section instead of duplicating it in the contributing guidelines.

I think this is work that @malvikasharan will be doing for the Community Handbook volume of the Turing Way and it just hasn't sifted to the top of the TODO list yet. But the idea is that that volume is a meta book on The Turing Way, how to contribute, etc.

Also, you dont need to be a superuser to build using a container. You can just use singularity to execute jupyter-book build . in the docker container. Takes a bit longer the first time but works like a charm as long as you only execute shell commands

To some people in our community, running a container and "only" executing shell commands _is_ being a super user. It's not being a super user to _us_ (you and me in this conversation), but we need to recognise that we have different experiences and training to other members of this community. For example, I'm thinking of those working on the Ethics chapters who may have only signed up to GitHub to make that contribution. They couldn't run a container and that shouldn't pose a barrier to adding a new chapter, but we can provide the option if they want to jump in at the deep end.

[sgibson91]

I think the tension here is that yes, technologically we want to practice what we preach, but we also want to be representative of the diverse ways in which data science is happening and all the different aspects that needs to be taken into account, e.g. ethics. We are no longer "just" about reproducibility. In order to include experiences from different disciplines, we have to meet those in the community who may not be so technologically focussed where they are.

I'm not arguing that this isn't a cool thing to include, it would be. I just want to really think about how much value it's adding and how it will effect the community before we dive in to all the technical magic :)

[malvikasharan]

I am chiming in to confirm everything Sarah said about the community handbook that captures the process of The Turing Way (several chapters for that are in the PRs).

On the conversation of simplicity vs complexity: I think our target readers are of all levels, beginner to pro. As Sarah said, many of our ethics contributors are beginners and they would rather make a branch/fork and contribute on the web interface. I am not a pro. I use local build to test how the book renders and what errors can be fixed before creating a PR. I can definitely see the use of a container to avoid installing the dependencies locally (#1016).

Taking my experience as a technical trainer, show/use one approach based on skill level (in this case it could be 3, GitHub - beginners, local and venv/containers - intermediate and advanced users). Too many options can confuse people, both who are using it and people who are supposed to provide support with the process.

Having said all that, @kkmann, you are welcome to test other feasible ways to use The Turing Way, and it would be useful to record the workflow. We can add in the handbook (as Sarah pointed) for interested users who want alternative ways to build the book. However, I would suggest keeping the contributing file simple and straightforward as that's our onboarding document for people who are starting off to learn about the project.

[kkmann]

I don't necessarily see any tension here. I am completely on board with seeing that there are different backgrounds - which is exactly why I am proposing to extend the docs to make the guts of TTW more accessible.
I don't see how more options would make it any harder - as long as there is a clear indication of the recommended standard process.
I have my doubts about the netlify-based process necessarily being the simplest way though. I'd make the case that learning git(hub) collaboration (fork/clone/branch/comit/push/open pr) is quite hard and might exclude some people. I certainly recall my initial git-horror x) Coll tool, but not necessarily user firendly in the classical sense...

So, I guess I'd be in favour of providing two officially supported 'build the book' routes.

1. netlify as is ('learn GitHub first')
2. conda-based local build ('play around locally, worry about git later')

This would provide two equally 'easy' entry routes depending on prior knowledge.

repo2docker is then an optional add-on; primarily for showcasing the tech (and nerds who think that switching conda environments is too much of a hassle)

@malvikasharan I guess the next question is where? Since this is primarily a technical doc, I would have suggested the new RR case-study section. My impression from the PRs of the community book is that it is more geared towards the non-technical aspects of TTW. That would keep the distinction between the Guide to RR and the Community Handbook sharp.

[malvikasharan]

As a case study, it definitely fits well in the chapter of case studies you started. A link to that can be included here: https://github.com/alan-turing-institute/the-turing-way/blob/master/book/README.md.

[sgibson91]

I also wouldn't use repo2docker for this if the goal is just to set up the env and run jupyter-book build . inside it. We won't need the Jupyter server for that and also r2d images aren't directly compatible with docker run (you have to do some port-forwarding for the Jupyter server). I think just a straight forward docker-compose or Dockerfile would suffice for those who want to develop locally. And we can use this action for the CI/CD workflow.

[kkmann]

Just checked the repo2docker approach - works fine (can't speak on interactive content).

It would be more consistent to have a conda environment specification though (that's also already documented in TTW). Providing a pre-built container to use instead of repo2docker locally is then of limited use (strike?).

That would boil down to

1. changing the environment specs in book/website to a conda environment
2. documenting approaches in the example section:
   
   
   
   1. netlify-first
   
   
   2. conda-first
   
   
   3. repo2docker-first
   
   
3. link in the community handbook, pointing out the intended audiance/background for each of the methods

[sgibson91]

Just checked the repo2docker approach - works fine (can't speak on interactive content).

I didn't mean that it wouldn't work, just that it's not the appropriate tool for the job considering we're not hosting notebooks. An r2d image will be (relatively) huge because a (unused) Jupyter server is installed.

For a test case/case study, I think it'll be fine with the caveat on why it's not a part of the original process?

[malvikasharan]

@kkmann I took the liberty to rename this issue to avoid ambiguity on this discussion.

[kkmann]

Sure sure, also r2d size doesn't really matter locally - I know it's making IT folks cringe to have unnecessary stuff in a container. It just works so nicely ;)

@sgibson91 what's you opinion on switching to a conda environment for consistency? I guess with that done, the rest is just documenting the different approaches.

[sgibson91]

Sure sure, also r2d size doesn't really matter locally - I know it's making IT folks cringe to have unnecessary stuff in a container. It just works so nicely ;)

Sorry, I was thinking about having a pre-built image ready to go and docker pull time.

@sgibson91 what's you opinion on switching to a conda environment for consistency? I guess with that done, the rest is just documenting the different approaches.

I LOVE conda environments!

[kkmann]

It's a WRAP <3

[kkmann]

@sgibson91 new insight: jupyter-book + datascience are not available on conda(-forge); guess that means we can scrap the conda environment approach (might make for a good negative example though).

That raises the question as to how to reproduce the turing way. Since https://github.com/alan-turing-institute/the-turing-way/blob/master/book/website/requirements.txt does not specify versions exactly, strictly speaking, the build is not reproducible.

You might want to object against fixing the package versions in requirements.txt to stay up to date. That would bring us back to building a container on each push to master and putting it on dockerhub (convenient but not 'lean' by using r2d).

Sorry for unwrapping, but I think if we want the Turing Way itself to be reproducible, we should do it properly (or just silently drop the issue ;)).

[sgibson91]

I actually think we should pin packages as upgrading the jupyter book is not a trivial task (or at least it wasn't last time, probably due to the huge rewrite of the backend of jupyter book), therefore pinning allows us to choose when we do that :)

[kkmann]

Cool, that makes it easier and I could just add a description of virtualenv in the section on reproducible environments.