diff --git a/README.md b/README.md index b18453dda..c85c58132 100644 --- a/README.md +++ b/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. diff --git a/docs/_config.yml b/docs/_config.yml index 2ebc7a003..2fd155a16 100644 --- a/docs/_config.yml +++ b/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: diff --git a/docs/_includes/notebook_colab_link.html b/docs/_includes/notebook_colab_link.html new file mode 100644 index 000000000..ccc04fa97 --- /dev/null +++ b/docs/_includes/notebook_colab_link.html @@ -0,0 +1,5 @@ +
+ + Open In Colab + +
diff --git a/docs/_layouts/page.html b/docs/_layouts/page.html index 6962addaa..a0f8004d6 100644 --- a/docs/_layouts/page.html +++ b/docs/_layouts/page.html @@ -5,6 +5,9 @@

{{ page.title }}

+ {% if page.nb_path %} + {% unless site.default_badges.colab != true or page.hide_colab_badge %}{% include notebook_colab_link.html %}{% endunless %} + {% endif -%}
{% if page.simple_map == true %} diff --git a/docs/clean.html b/docs/clean.html index 3147946ea..b72db7a8d 100644 --- a/docs/clean.html +++ b/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" ---