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 1. Create an Heroku App
Install Heroku toolbelt from https://devcenter.heroku.com/articles/heroku-cli and run:
heroku create appname
Copy the generated URL (i.e. https://appname.herokuapp.com/).
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
doc_host = doc_base =
Then to build the nbdev docs run:
nbdev_build_docs --force_all True git add docs/ README.md git commit -m "Update docs."
Then install jekyll-auth:
cd docs echo "gem 'jekyll-auth'" >> Gemfile bundle install jekyll-auth new
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]
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.