Add ability to have Colab badges on pages (#210)

* add ability to have colab badges

* correct page

* back out config changes

* clean up includes

* remove top padding of TOC

* added docs re: Colab

* added docs re: Colab

* build docs and add html

* correct mismatch in README

* sync notebooks

README.md

@@ -67,7 +67,7 @@ Now, run `jupyter notebook`, and click `00_core.ipynb`. This is where you'll cre
 
 In the last cell of your notebook, you can then run:
 
-```
+```python
 from nbdev import *
 notebook2script()
 ```
@@ -173,6 +173,28 @@ For adding search to your docs site, nbdev supports [Google Custom Search](https
 
 Although we can't fully automate the creation of the search engine (since you need to login to Google to do it) we have made it very easy. Here are the steps you need to follow: [Setting up search](https://nbdev.fast.ai/search).
 
+### Google Colab Badges
+
+Because both the documentation and code for nbdev is written in notebooks, you can optionally view and run nbdev documentation in [Google Colab](https://colab.research.google.com/). You can enable Google Colab badges that link to the appropriate notebook(s) in your GitHub repository.  
+
+You can toggle the this feature on or off in your `/_config.yml` file:
+
+```yaml
+# This specifies what badges are turned on by default for notebook docs.
+default_badges:
+  colab: true
+```
+
+Furthermore, If you want to hide a badge on an individual document but still show badges elsewhere, you can set the front matter `hide_colab_badge: true`.  For example, if you wanted to hide the Colab badge from showing up on the notebook `nbs/06_cli.ipynb`, your front matter (in the form of a markdown cell at the top of the notebook will look like this:
+
+```
+# Command line functions
+> Console commands added by the nbdev library
+
+- hide_colab_badge:true```
+
+Note how in the above example, the title `Command line functions` is formatted as a markdown heading and the summary `Console commands added by the nbdev library` is formatted as a markdown block quote. The additional option `hide_colab_badge` is a list item.  It is important that this list item is separated from the summary by 2 newlines as shown above, in the same notebook markdown cell.
+
 ## Contributing
 
 If you want to contribute to `nbdev`, be sure to review the [contributions guidelines](https://github.com/fastai/nbdev/blob/master/CONTRIBUTING.md). This project adheres to fastai`s [code of conduct](https://github.com/fastai/nbdev/blob/master/CODE-OF-CONDUCT.md). By participating, you are expected to uphold this code. In general, the fastai project strives to abide by generally accepted best practices in open-source software development.

docs/_config.yml

@@ -21,6 +21,10 @@ exclude:
 
 exclude: [vendor]
 
+# This specifies what badges are turned on by default for notebook docs.
+default_badges:
+  colab: true
+
 highlighter: rouge
 markdown: kramdown
 kramdown:

docs/_includes/notebook_colab_link.html

@@ -0,0 +1,5 @@
+<div class="px-2">
+    <a href="https://colab.research.google.com/github/{{site.repository}}/blob/{{page.branch | default: "master"}}/{{page.nb_path}}" target="_blank">
+        <img class="notebook-badge-image" src="{{ "images/colab.svg" | relative_url }}" alt="Open In Colab"/>
+    </a>
+</div>

docs/_layouts/page.html

@@ -5,6 +5,9 @@
 <div class="post-header">
     <a id="{{page.title}}"></a>
     <h1 class="post-title-main">{{ page.title }}</h1>
+    {% if page.nb_path %}
+        {% unless site.default_badges.colab != true or page.hide_colab_badge %}{% include notebook_colab_link.html %}{% endunless %}
+    {% endif -%}
 </div>
 
 {% if page.simple_map == true %}

docs/clean.html

@@ -7,6 +7,7 @@
 
 summary: "Strip notebooks from superfluous metadata"
 description: "Strip notebooks from superfluous metadata"
+nb_path: "nbs/07_clean.ipynb"
 ---
 <!--
 

docs/conda.html

@@ -7,6 +7,7 @@
 
 summary: "Pure python packages created from settings.ini"
 description: "Pure python packages created from settings.ini"
+nb_path: "nbs/05a_conda.ipynb"
 ---
 <!--
 

docs/css/customstyles.css

@@ -333,7 +333,7 @@ div#toc >ul::before {
     margin-left:auto;
     margin-right:auto;
     width:70px;
-    padding-top:150px;
+    padding-top:0px;
     padding-bottom:40px;
     padding-left:10px;
 }
@@ -1333,3 +1333,7 @@ div.input + details {
 .output_wrapper{
     overflow: scroll;
 }
+
+.notebook-badge-image {
+  border:0 !important;
+}

docs/export.html

@@ -7,6 +7,7 @@
 
 summary: "The functions that transform notebooks in a library"
 description: "The functions that transform notebooks in a library"
+nb_path: "nbs/00_export.ipynb"
 ---
 <!--
 
@@ -73,7 +74,7 @@ <h2 id="Basic-foundations">Basic foundations<a class="anchor-link" href="#Basic-
 
 
 <div class="output_markdown rendered_html output_subarea ">
-<h3 id="Config" class="doc_header"><code>Config</code><a href="https://github.com/fastai/nbdev/tree/master/nbdev/imports.py#L36" class="source_link" style="float:right">[source]</a></h3><blockquote><p><code>Config</code>(<strong><code>cfg_name</code></strong>=<em><code>'settings.ini'</code></em>)</p>
+<h3 id="Config" class="doc_header"><code>Config</code><a href="https://github.com/fastai/nbdev/tree/master/nbdev/imports.py#L37" class="source_link" style="float:right">[source]</a></h3><blockquote><p><code>Config</code>(<strong><code>cfg_name</code></strong>=<em><code>'settings.ini'</code></em>)</p>
 </blockquote>
 <p>Store the basic information for nbdev to work</p>
 
@@ -156,7 +157,7 @@ <h3 id="Config" class="doc_header"><code>Config</code><a href="https://github.co
 
 
 <div class="output_markdown rendered_html output_subarea ">
-<h4 id="last_index" class="doc_header"><code>last_index</code><a href="https://github.com/fastai/nbdev/tree/master/nbdev/imports.py#L64" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>last_index</code>(<strong><code>x</code></strong>, <strong><code>o</code></strong>)</p>
+<h4 id="last_index" class="doc_header"><code>last_index</code><a href="https://github.com/fastai/fastcore/tree/master/fastcore/utils.py#L142" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>last_index</code>(<strong><code>x</code></strong>, <strong><code>o</code></strong>)</p>
 </blockquote>
 <p>Finds the last index of occurence of <code>x</code> in <code>o</code> (returns -1 if no occurence)</p>
 
@@ -200,7 +201,7 @@ <h4 id="last_index" class="doc_header"><code>last_index</code><a href="https://g
 
 
 <div class="output_markdown rendered_html output_subarea ">
-<h4 id="compose" class="doc_header"><code>compose</code><a href="https://github.com/fastai/nbdev/tree/master/nbdev/imports.py#L97" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>compose</code>(<strong>*<code>funcs</code></strong>, <strong><code>order</code></strong>=<em><code>None</code></em>)</p>
+<h4 id="compose" class="doc_header"><code>compose</code><a href="https://github.com/fastai/fastcore/tree/master/fastcore/utils.py#L363" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>compose</code>(<strong>*<code>funcs</code></strong>, <strong><code>order</code></strong>=<em><code>None</code></em>)</p>
 </blockquote>
 <p>Create a function that composes all functions in <code>funcs</code>, passing along remaining <code>*args</code> and <code>**kwargs</code> to all</p>
 
@@ -246,7 +247,7 @@ <h4 id="compose" class="doc_header"><code>compose</code><a href="https://github.
 
 
 <div class="output_markdown rendered_html output_subarea ">
-<h4 id="parallel" class="doc_header"><code>parallel</code><a href="https://github.com/fastai/nbdev/tree/master/nbdev/imports.py#L128" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>parallel</code>(<strong><code>f</code></strong>, <strong><code>items</code></strong>, <strong>*<code>args</code></strong>, <strong><code>n_workers</code></strong>=<em><code>None</code></em>, <strong>**<code>kwargs</code></strong>)</p>
+<h4 id="parallel" class="doc_header"><code>parallel</code><a href="https://github.com/fastai/fastcore/tree/master/fastcore/utils.py#L702" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>parallel</code>(<strong><code>f</code></strong>, <strong><code>items</code></strong>, <strong>*<code>args</code></strong>, <strong><code>n_workers</code></strong>=<em><code>4</code></em>, <strong><code>total</code></strong>=<em><code>None</code></em>, <strong><code>progress</code></strong>=<em><code>None</code></em>, <strong><code>pause</code></strong>=<em><code>0</code></em>, <strong>**<code>kwargs</code></strong>)</p>
 </blockquote>
 <p>Applies <code>func</code> in parallel to <code>items</code>, using <code>n_workers</code></p>
 
@@ -305,7 +306,7 @@ <h4 id="parallel" class="doc_header"><code>parallel</code><a href="https://githu
 
 
 <div class="output_markdown rendered_html output_subarea ">
-<h4 id="first" class="doc_header"><code>first</code><a href="https://github.com/fastai/nbdev/tree/master/nbdev/export.py#L15" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>first</code>(<strong><code>x</code></strong>)</p>
+<h4 id="first" class="doc_header"><code>first</code><a href="https://github.com/fastai/fastcore/tree/master/fastcore/utils.py#L197" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>first</code>(<strong><code>x</code></strong>)</p>
 </blockquote>
 <p>First element of <code>x</code>, or None if missing</p>
 
@@ -495,7 +496,7 @@ <h4 id="read_nb" class="doc_header"><code>read_nb</code><a href="https://github.
 
 <div class="inner_cell">
     <div class="input_area">
-<div class=" highlight hl-ipython3"><pre><span></span><span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">test_nb</span><span class="p">[</span><span class="s1">&#39;nbformat&#39;</span><span class="p">]</span><span class="si">}</span><span class="s2">.</span><span class="si">{</span><span class="n">test_nb</span><span class="p">[</span><span class="s1">&#39;nbformat_minor&#39;</span><span class="p">]</span><span class="si">}</span><span class="s2">&quot;</span>
+<div class=" highlight hl-ipython3"><pre><span></span><span class="sa">f</span><span class="s2">&quot;</span><span class="si">{test_nb[&#39;nbformat&#39;]}</span><span class="s2">.</span><span class="si">{test_nb[&#39;nbformat_minor&#39;]}</span><span class="s2">&quot;</span>
 </pre></div>
 
     </div>
@@ -816,13 +817,13 @@ <h4 id="is_export" class="doc_header"><code>is_export</code><a href="https://git
 <span class="n">cell</span><span class="p">[</span><span class="s1">&#39;source&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;%nbdev_export mod</span><span class="se">\n</span><span class="s2">from nbdev.imports import *&quot;</span>
 <span class="n">test_eq</span><span class="p">(</span><span class="n">is_export</span><span class="p">(</span><span class="n">cell</span><span class="p">,</span> <span class="s1">&#39;export&#39;</span><span class="p">),</span> <span class="p">(</span><span class="s1">&#39;mod&#39;</span><span class="p">,</span> <span class="kc">True</span><span class="p">))</span>
 <span class="n">cell</span><span class="p">[</span><span class="s1">&#39;source&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;# export mod.file&quot;</span>
-<span class="n">test_eq</span><span class="p">(</span><span class="n">is_export</span><span class="p">(</span><span class="n">cell</span><span class="p">,</span> <span class="s1">&#39;export&#39;</span><span class="p">),</span> <span class="p">(</span><span class="sa">f</span><span class="s1">&#39;mod</span><span class="si">{</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">sep</span><span class="si">}</span><span class="s1">file&#39;</span><span class="p">,</span> <span class="kc">True</span><span class="p">))</span>
+<span class="n">test_eq</span><span class="p">(</span><span class="n">is_export</span><span class="p">(</span><span class="n">cell</span><span class="p">,</span> <span class="s1">&#39;export&#39;</span><span class="p">),</span> <span class="p">(</span><span class="sa">f</span><span class="s1">&#39;mod</span><span class="si">{os.path.sep}</span><span class="s1">file&#39;</span><span class="p">,</span> <span class="kc">True</span><span class="p">))</span>
 <span class="n">cell</span><span class="p">[</span><span class="s1">&#39;source&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;%nbdev_export mod.file&quot;</span>
-<span class="n">test_eq</span><span class="p">(</span><span class="n">is_export</span><span class="p">(</span><span class="n">cell</span><span class="p">,</span> <span class="s1">&#39;export&#39;</span><span class="p">),</span> <span class="p">(</span><span class="sa">f</span><span class="s1">&#39;mod</span><span class="si">{</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">sep</span><span class="si">}</span><span class="s1">file&#39;</span><span class="p">,</span> <span class="kc">True</span><span class="p">))</span>
+<span class="n">test_eq</span><span class="p">(</span><span class="n">is_export</span><span class="p">(</span><span class="n">cell</span><span class="p">,</span> <span class="s1">&#39;export&#39;</span><span class="p">),</span> <span class="p">(</span><span class="sa">f</span><span class="s1">&#39;mod</span><span class="si">{os.path.sep}</span><span class="s1">file&#39;</span><span class="p">,</span> <span class="kc">True</span><span class="p">))</span>
 <span class="n">cell</span><span class="p">[</span><span class="s1">&#39;source&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;# exporti mod.file&quot;</span>
-<span class="n">test_eq</span><span class="p">(</span><span class="n">is_export</span><span class="p">(</span><span class="n">cell</span><span class="p">,</span> <span class="s1">&#39;export&#39;</span><span class="p">),</span> <span class="p">(</span><span class="sa">f</span><span class="s1">&#39;mod</span><span class="si">{</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">sep</span><span class="si">}</span><span class="s1">file&#39;</span><span class="p">,</span> <span class="kc">False</span><span class="p">))</span>
+<span class="n">test_eq</span><span class="p">(</span><span class="n">is_export</span><span class="p">(</span><span class="n">cell</span><span class="p">,</span> <span class="s1">&#39;export&#39;</span><span class="p">),</span> <span class="p">(</span><span class="sa">f</span><span class="s1">&#39;mod</span><span class="si">{os.path.sep}</span><span class="s1">file&#39;</span><span class="p">,</span> <span class="kc">False</span><span class="p">))</span>
 <span class="n">cell</span><span class="p">[</span><span class="s1">&#39;source&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;%nbdev_export_internal mod.file&quot;</span>
-<span class="n">test_eq</span><span class="p">(</span><span class="n">is_export</span><span class="p">(</span><span class="n">cell</span><span class="p">,</span> <span class="s1">&#39;export&#39;</span><span class="p">),</span> <span class="p">(</span><span class="sa">f</span><span class="s1">&#39;mod</span><span class="si">{</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">sep</span><span class="si">}</span><span class="s1">file&#39;</span><span class="p">,</span> <span class="kc">False</span><span class="p">))</span>
+<span class="n">test_eq</span><span class="p">(</span><span class="n">is_export</span><span class="p">(</span><span class="n">cell</span><span class="p">,</span> <span class="s1">&#39;export&#39;</span><span class="p">),</span> <span class="p">(</span><span class="sa">f</span><span class="s1">&#39;mod</span><span class="si">{os.path.sep}</span><span class="s1">file&#39;</span><span class="p">,</span> <span class="kc">False</span><span class="p">))</span>
 <span class="n">cell</span><span class="p">[</span><span class="s1">&#39;source&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;# expt mod.file&quot;</span>
 <span class="k">assert</span> <span class="n">is_export</span><span class="p">(</span><span class="n">cell</span><span class="p">,</span> <span class="s1">&#39;export&#39;</span><span class="p">)</span> <span class="ow">is</span> <span class="kc">None</span>
 <span class="n">cell</span><span class="p">[</span><span class="s1">&#39;source&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;# exportmod.file&quot;</span>