Nbdev is a python library developed by fast.ai that makes it very convenient to create libraries and documentation from Jupyter Notebooks. To learn more about nbdev and it’s applications check out the documentation at nbdev.fast.ai (in a brilliant recursive manner generated with nbdev itself) or read our other blog post on how and why we have been using nbdev in our team, how it has improved our workflow and what the best practices are that we have found.
One of the problems we encountered with using nbdev for generating our documentation is that some of our documentation contains sensitive customer data and other information that we want to keep secure, which means that we don’t want to host it on a public Github pages website.
To solve this issue we use jekyll-auth which makes it very easy to host a Jekyll website on Heroku using Github authentication. The beauty of this solution is that you can immediately give your entire Github organization or Github team access to the documentation.
Making your nbdev documentation an authenticated Heroku app is done very quickly following a few simple steps.
Step 2. Create an OAuth App in Github
Go to https://github.com/organizations/[org_name]/settings/applications/ and create a new OAuth App and set the homepage URL to https://appname.herokuapp.com/ and the callback URL to https://appname.herokuapp.com/auth/github/callback using the same
appname as earlier (important). Keep the tab with the generated
CLIENT_SECRET open for later use.
Step 3. Upload to Heroku
For some reason, when hosting the nbdev docs on Heroku the URLs will only work when there is no host or base URL set. So, before building your docs make sure to set doc_host and doc_base to None in your app’s nbdev
Then to build the nbdev docs run:
Then install jekyll-auth:
Now set the
CLIENT_SECRET from your Github OAuth application in Heroku. Also adding either your
GITHUB_ORG_NAMEas written in your Github Organisation URL (i.e. 20treeAI in our case https://github.com/organizations/20treeAI/) or your
GITHUB_TEAM_ID (to find you Team ID check the instructions at the bottom of the Jekyll-Auth Getting Started doc).
heroku config:set GITHUB_CLIENT_ID=[CLIENT_ID] GITHUB_CLIENT_SECRET=[CLIENT_SECRET] GITHUB_ORG_NAME=[ORG_NAME] # or GITHUB_TEAM_ID=[TEAM_ID]
Then install and push to Heroku using:
You should now be able to visit the website typing
heroku open in the terminal.
After allowing access you should be able to see your documentation.
Step 4. Updating the Docs
Then to update the docs on Heroku run the following code from the app directory (not from docs):
If for some reason you deleted your Heroku remote, you can run the following code before pushing to Heroku.
heroku git:remote -a appname
Or if you have a merge conflict for example because of unrelated git histories (this can happen if you squash commits locally but not on Heroku) or because the local branch is somehow behind, you can reset the repo before pushing to Heroku.
This is how we have been using jekyll-auth to make our nbdev documentation easily accessible to our team members. Hopefully, this will be useful to other teams around the world.