Auto-Generated Authenticated Python Docs using nbdev and Heroku

Nbdev is a python library developed by 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 (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.

Install Heroku toolbelt from and run:

heroku create appname

Copy the generated URL (i.e.

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.

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/
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 or your GITHUB_TEAM_ID (to find you Team ID check the instructions at the bottom of the Jekyll-Auth Getting Started doc).

Image for post

Image for post

Then install and push to Heroku using:

git add Rakefile 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
Image for post

Image for post

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.
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.
index.ipynb with the generated documentation from this notebook next to it.

Then to update the docs on Heroku run the following code from the appdirectory (not from docs):

nbdev_build_docs --force_all True
git add docs/
git commit -m "Update docs."
git subtree push --prefix docs/ heroku master
heroku open

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.


This website of Overstory B.V. (the “Owner”), which is available at (the “Website”), uses Cookies and similar technologies in order to ensure the correct functioning of its services and to improve the navigation experience of the users. This document provides detailed information regarding the use of Cookies and similar technologies and how they are used in the Website.

What are Cookies?

Cookies are text files containing small amounts of information that are downloaded to your device when you visit a website. Cookies are then sent back to the originating web domain on your subsequent visits to that domain. Most web pages contain elements from multiple web domains so when you visit the website, your browser may receive cookies from several sources.

Cookies are useful because they allow a website to recognise a user’s device, allowing you to navigate between pages efficiently and to remember preferences and generally improve the user experience.

Session cookies are deleted automatically when you close your browser and persistent cookies remain on your device after the browser is closed (for example to remember your user preferences when you return to the Website).

For further information, please visit

What categories of Cookies are used by the Website?

The Cookies used on the Website are described hereinafter:

  • Strictly necessary Cookies
    This Website uses Cookies to save the User’s session and to carry out other activities that are strictly necessary for the operation of this Website, for example in relation to the distribution of traffic. These cookies are essential in order to enable you to move around the Website and use its features.
  • Performance Cookies
    This Website uses Cookies to save browsing preferences and to optimise the User’s browsing experience. Among these Cookies are, for example, those used for the setting of language or for the management of first party statistics employed directly by the Owner of the Website.
    The services contained in this section enable the Owner to monitor and analyse web traffic and can be used to keep track of User behaviour. This allows us to provide a high quality experience by customising our offering and quickly identifying and fixing any issues that arise.
    Some of the services listed below collect statistics in an anonymised and aggregated form and may not require the consent of the User or may be managed directly by the Owner – depending on how they are described – without the help of third parties.
    If any third party operated services are listed among the tools below, these may be used to track Users’ browsing habits – in addition to the information specified herein and without the Owner’s knowledge. Please refer to the privacy policy of the listed services for detailed information.
 Cookie Name Source Purpose Further Information










Google Analytics

Google uses the data collected to track and examine the use of this Website (e.g. how visitors use the Website), to prepare reports on its activities and share them with other Google services.

Google may use the data collected to contextualise and personalise the ads of its own advertising network.

Stores timestamp and cookie domain/path

Stores properties set by addEventProperties API)

Google Analytics is a web analysis service provided by Google LLC (“Google”).

Personal Data collected: Cookies and Usage Data.

Place of processing: United States – Privacy PolicyOpt Out; Ireland – Privacy Policy. Privacy Shield participant.

Click here for Google’s privacy policy in respect of Google Analytics

You may opt out of tracking by Google Analytics by visiting

  • Managing contacts and sending messages Cookies
    This type of cookies makes it possible to manage a database of email contacts, phone contacts or any other contact information to communicate with the User. These services may also collect data concerning the date and time when the message was viewed by the User, as well as when the User interacted with it, such as by clicking on links included in the message.

How you can provide or withdraw consent to the installation of Cookies?

Some of the purposes for which Cookies are installed may also require the User’s consent. You will have seen a pop up to this effect on your first visit to this website. Although it will not usually appear on subsequent visits, you may withdraw your consent at any time by following the instructions set below.

Where the installation of Cookies is based on consent, such consent can be freely withdrawn at any time following the instructions provided in this document.

In addition to what is specified in this document, you can manage preferences for Cookies directly from within your own browser and prevent – for example – third parties from installing Cookies.

Through browser preferences, it is also possible to delete Cookies installed in the past, including the Cookies that may have saved the initial consent for the installation of Cookies by this website.

Users can, for example, find information about how to manage Cookies in the most commonly used browsers at the following addresses: Google Chrome, Mozilla Firefox, Apple Safari and Microsoft Internet Explorer.

With regard to Cookies installed by third parties, you can manage their preferences and withdrawal of your consent by clicking the related opt-out link (if provided), by using the means provided in the third party’s privacy policy, or by contacting the third party.

Limitations of liability

The Owner neither guarantees, nor is liable for damages or harm of any nature that may result from the following circumstances:

  1. Lack of operation of the Website or its incorrect performance;
  2. Lack of usefulness, suitability or validity of the services and content provided on the Website regarding the results and expectations of the User;
  3. Existence of viruses or programmes on the User’s computer.

The Owner shall not be liable, in any circumstance, including negligence, for loss of business, access, benefits, data, for indirect, secondary, special or consequential damages resulting from the access or use of services of the Website, or that are otherwise within its scope.
Since the installation of third party Cookies and other tracking systems through the services used within this Website cannot be technically controlled by the Owner, the Owner cannot be held responsible for the installation and use of such Cookies.
Therefore, any specific references to Cookies and tracking systems installed by third parties are to be considered indicative. In order to obtain complete information, you are kindly requested to consult both the cookies and privacy policies for the respective third party services listed in this document

Updates to the Cookies Policy

After your initial visit to the Website we may change the Cookies we use. This Cookies Policy will always allow you to know who is placing Cookies, for what purpose and give you the means to disable them so please regularly consult our Website in order to be always aware of the rules applicable to the use of Cookies.


The Website is owned by Overstory B.V., with registered office at Weesperstraat 61-105, 1018VN, Amsterdam, The Netherlands.

For any questions regarding this Cookies Policy, please contact us at

Given the objective complexity surrounding the identification of technologies based on Cookies, Users are encouraged to contact the Owner should they wish to receive any further information on the use of Cookies by this Website.