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 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 settings.inias follows:

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_ID and 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:

bundle
git add Rakefile config.ru Gemfile Gemfile.lock
git commit -m "Add jekyll-auth to docs."
cd .. # go to upper directory to only push docs to heroku
git subtree push --prefix docs/ heroku master
heroku open

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.

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.

heroku repo:reset

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.

Other Resources

• nbdev.fast.ai
• Jekyll-Auth Getting Started
• How nbdev helps us structure our data science workflow in Jupyter Notebooks