From 080c5ae9fa815c44afa40f02a4c2eb5ebd603eed Mon Sep 17 00:00:00 2001 From: Hamel Husain Date: Mon, 10 Aug 2020 18:24:55 -0700 Subject: [PATCH 01/10] add ability to have colab badges --- docs/_config.yml | 7 +++++++ docs/_includes/notebook_colab_link.html | 5 +++++ docs/_layouts/page.html | 5 +++-- docs/css/customstyles.css | 4 ++++ docs/images/colab.svg | 1 + nbdev/templates/jekyll.tpl | 1 + 6 files changed, 21 insertions(+), 2 deletions(-) create mode 100644 docs/_includes/notebook_colab_link.html create mode 100644 docs/images/colab.svg diff --git a/docs/_config.yml b/docs/_config.yml index 2ebc7a003..e4ce251ec 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -21,6 +21,13 @@ exclude: exclude: [vendor] +# This specifies what badges are turned on by default for notebook docs. +default_badges: + colab: true + +github_username: fastai +github_repo: nbdev + 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..9dd1f3e22 --- /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..8df094297 100644 --- a/docs/_layouts/page.html +++ b/docs/_layouts/page.html @@ -5,6 +5,9 @@

{{ page.title }}

+ {% if page.nb_path and site.github_username and site.github_repo %} + {% unless site.default_badges.colab != true %}{% include notebook_colab_link.html %}{% endunless %} + {% endif -%}
{% if page.simple_map == true %} @@ -30,11 +33,9 @@

{{ page.title }}

{% endif %}
- {% if page.summary %}
{{page.summary}}
{% endif %} - {% unless page.toc == false %} {% include toc.html %} {% endunless %} diff --git a/docs/css/customstyles.css b/docs/css/customstyles.css index 1325fdb63..adb2d75f9 100644 --- a/docs/css/customstyles.css +++ b/docs/css/customstyles.css @@ -1333,3 +1333,7 @@ div.input + details { .output_wrapper{ overflow: scroll; } + +.notebook-badge-image { + border:0 !important; +} diff --git a/docs/images/colab.svg b/docs/images/colab.svg new file mode 100644 index 000000000..c08066ee3 --- /dev/null +++ b/docs/images/colab.svg @@ -0,0 +1 @@ + Open in ColabOpen in Colab diff --git a/nbdev/templates/jekyll.tpl b/nbdev/templates/jekyll.tpl index 1cb693459..92b016464 100644 --- a/nbdev/templates/jekyll.tpl +++ b/nbdev/templates/jekyll.tpl @@ -7,6 +7,7 @@ sidebar: home_sidebar {% if resources.tags != "" and resources.tags != nil %}tags: {{resources.tags}}{% endif %} {% if resources.summary != "" and resources.summary != nil %}summary: "{{resources.summary}}"{% endif %} {% if resources.summary != "" and resources.summary != nil %}description: "{{resources.summary}}"{% endif %} +{% if resources.nb_path != "" and resources.nb_path != nil %}nb_path: "{{resources.nb_path}}"{% endif %} --- {% include 'autogen.tpl' %} From 824352470c9e40376ec464b3be112edd175856fb Mon Sep 17 00:00:00 2001 From: Hamel Husain Date: Mon, 10 Aug 2020 18:27:12 -0700 Subject: [PATCH 02/10] correct page --- docs/_layouts/page.html | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/_layouts/page.html b/docs/_layouts/page.html index 8df094297..fb3b4c141 100644 --- a/docs/_layouts/page.html +++ b/docs/_layouts/page.html @@ -33,9 +33,11 @@

{{ page.title }}

{% endif %}
+ {% if page.summary %}
{{page.summary}}
{% endif %} + {% unless page.toc == false %} {% include toc.html %} {% endunless %} From 4214b131237b47dab332e8bb9d0fc50c96961239 Mon Sep 17 00:00:00 2001 From: Hamel Husain Date: Mon, 10 Aug 2020 18:31:57 -0700 Subject: [PATCH 03/10] back out config changes --- docs/_config.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/_config.yml b/docs/_config.yml index e4ce251ec..2fd155a16 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -25,9 +25,6 @@ exclude: [vendor] default_badges: colab: true -github_username: fastai -github_repo: nbdev - highlighter: rouge markdown: kramdown kramdown: From 15679fb9c7d66a901985d8d011667fc2e1e05f47 Mon Sep 17 00:00:00 2001 From: Hamel Husain Date: Mon, 10 Aug 2020 18:32:49 -0700 Subject: [PATCH 04/10] clean up includes --- docs/_includes/notebook_colab_link.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_includes/notebook_colab_link.html b/docs/_includes/notebook_colab_link.html index 9dd1f3e22..ccc04fa97 100644 --- a/docs/_includes/notebook_colab_link.html +++ b/docs/_includes/notebook_colab_link.html @@ -1,5 +1,5 @@
- + Open In Colab
From 27e29f2a4e07f5c7026a01f6c36e0c3ea5386a6b Mon Sep 17 00:00:00 2001 From: Hamel Husain Date: Mon, 10 Aug 2020 19:27:02 -0700 Subject: [PATCH 05/10] remove top padding of TOC --- docs/css/customstyles.css | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/css/customstyles.css b/docs/css/customstyles.css index adb2d75f9..c6b0ee26d 100644 --- a/docs/css/customstyles.css +++ b/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; } From 95cc7facf49e5072257225c342113b80748f7167 Mon Sep 17 00:00:00 2001 From: Hamel Husain Date: Mon, 10 Aug 2020 21:36:23 -0700 Subject: [PATCH 06/10] added docs re: Colab --- nbs/index.ipynb | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/nbs/index.ipynb b/nbs/index.ipynb index 3899ed7e0..4befb8751 100644 --- a/nbs/index.ipynb +++ b/nbs/index.ipynb @@ -318,6 +318,41 @@ "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)." ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Google Colab Badges" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "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 of your docs in your GitHub repository. \n", + "\n", + "You can toggle the this feature on or off in your `/_config.yml` file:\n", + "\n", + "```yaml\n", + "# This specifies what badges are turned on by default for notebook docs.\n", + "default_badges:\n", + " colab: true\n", + "```\n", + "\n", + "Furthermore, If you only want to hide a badge on an individual document, you can set the front matter `hide_colab_badge: true`. For example, if you want a Colab badge to show up on all docs created with notebooks, except for the notebook `nbs/06_cli.ipynb`, your front matter (in the form of a markdown cell at the top of your notebook should look like this:\n", + "\n", + "\n", + "```\n", + "# Command line functions\n", + "\n", + "> Console commands added by the nbdev library\n", + "\n", + "- hide_colab_badge: true\n", + "```\n", + "\n", + "Note how in the above example, in addition to a title `Command line functions` (formatted as a markdown heading) and the summary `Console commands added by the nbdev library` (formatted as a markdown note) the additional option `hide_colab_badge` is a list item. It is important that the list item is separated from the summary by 2 newlines as shown above, in the same notebook markdown cell." + ] + }, { "cell_type": "markdown", "metadata": {}, @@ -365,6 +400,18 @@ "display_name": "Python 3", "language": "python", "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.7.6" } }, "nbformat": 4, From 2fe4673fdf33b213c629765ba5e04887acc2bc65 Mon Sep 17 00:00:00 2001 From: Hamel Husain Date: Mon, 10 Aug 2020 21:40:38 -0700 Subject: [PATCH 07/10] added docs re: Colab --- nbs/index.ipynb | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/nbs/index.ipynb b/nbs/index.ipynb index 4befb8751..9754cd4ea 100644 --- a/nbs/index.ipynb +++ b/nbs/index.ipynb @@ -329,7 +329,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "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 of your docs in your GitHub repository. \n", + "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. \n", "\n", "You can toggle the this feature on or off in your `/_config.yml` file:\n", "\n", @@ -339,8 +339,7 @@ " colab: true\n", "```\n", "\n", - "Furthermore, If you only want to hide a badge on an individual document, you can set the front matter `hide_colab_badge: true`. For example, if you want a Colab badge to show up on all docs created with notebooks, except for the notebook `nbs/06_cli.ipynb`, your front matter (in the form of a markdown cell at the top of your notebook should look like this:\n", - "\n", + "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:\n", "\n", "```\n", "# Command line functions\n", @@ -350,7 +349,7 @@ "- hide_colab_badge: true\n", "```\n", "\n", - "Note how in the above example, in addition to a title `Command line functions` (formatted as a markdown heading) and the summary `Console commands added by the nbdev library` (formatted as a markdown note) the additional option `hide_colab_badge` is a list item. It is important that the list item is separated from the summary by 2 newlines as shown above, in the same notebook markdown cell." + "Note how in the above example, th `Command line functions` (formatted as a markdown heading) and the summary `Console commands added by the nbdev library` (formatted as a markdown note) the additional option `hide_colab_badge` is a list item. It is important that the list item is separated from the summary by 2 newlines as shown above, in the same notebook markdown cell." ] }, { From dfda419acf7532af245d97f4b55c929068beeb1e Mon Sep 17 00:00:00 2001 From: Hamel Husain Date: Mon, 10 Aug 2020 21:47:22 -0700 Subject: [PATCH 08/10] build docs and add html --- README.md | 29 +++++++++++++-- docs/_layouts/page.html | 4 +-- docs/clean.html | 1 + docs/cli.html | 27 +++++++------- docs/conda.html | 1 + docs/export.html | 21 +++++------ docs/export2html.html | 21 +++++------ docs/flag_tests.html | 5 +-- docs/index.html | 26 ++++++++++++++ docs/merge.html | 3 +- docs/nbdev_callback_test.html | 3 +- docs/search.html | 1 + docs/showdoc.html | 67 +++++++++++++++-------------------- docs/sync.html | 1 + docs/test.html | 38 +------------------- docs/tutorial.html | 3 +- nbs/index.ipynb | 14 +------- 17 files changed, 134 insertions(+), 131 deletions(-) diff --git a/README.md b/README.md index b18453dda..e379129b3 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,10 @@ See below for *Installing* and *Getting Started*. In the other pages of the docu ## Installing -nbdev is is on PyPI and conda so you can just run `pip install nbdev` or `conda install -c fastai nbdev`. +nbdev is is on PyPI so you can just run: +``` +pip install nbdev +``` For an [editable install](https://stackoverflow.com/questions/35064426/when-would-the-e-editable-option-be-useful-with-pip-install), use the following: ``` @@ -67,7 +70,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 +176,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/_layouts/page.html b/docs/_layouts/page.html index fb3b4c141..a0f8004d6 100644 --- a/docs/_layouts/page.html +++ b/docs/_layouts/page.html @@ -5,8 +5,8 @@

{{ page.title }}

- {% if page.nb_path and site.github_username and site.github_repo %} - {% unless site.default_badges.colab != true %}{% include notebook_colab_link.html %}{% endunless %} + {% if page.nb_path %} + {% unless site.default_badges.colab != true or page.hide_colab_badge %}{% include notebook_colab_link.html %}{% endunless %} {% endif -%}
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" ---