Auto-Generated Authenticated Python Docs using nbdev and Heroku

David de Meij
Jan 15 · 4 min read

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/).

note that I had to use mycoolapp20 since mycoolapp was already taken on Heroku.
note that I had to use mycoolapp20 since mycoolapp was already taken on Heroku.
Note that I used mycoolapp20 because mycoolapp was already taken on Heroku.

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

doc_host = 
doc_base =

Then to build the nbdev docs run:

Then install jekyll-auth:

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:

You should now be able to visit the website typing heroku open in the terminal.

The first time it asks you to allow the app to verify your Github organization or team.

After allowing access you should be able to see your documentation.

index.ipynb with the generated documentation from this notebook next to it.

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.

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

20tree.ai

Exploring forests from the sky.

David de Meij

Written by

Data Scientist @ 20tree.ai. Focused on having a positive impact using AI.

20tree.ai

20tree.ai

Exploring forests from the sky.

More From Medium

More on Deep Learning from 20tree.ai

More on Deep Learning from 20tree.ai

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade