Merge pull request #694 from fastai/conditional-content

Conditional content for markdown vs HTML for README

Author: hamelsmu

README.md

@@ -3,13 +3,12 @@ Getting started
 
 <!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
 
-**NB: This is nbdev v2, a new from-scratch rewrite of nbdev that’s not
-backwards compatible. Whilst the differences to nbdev1 aren’t huge, it
-does require some changes. So if you wish to continue to use nbdev1
-until you’ve got the time to upgrade, you can find the old version docs
-at [nbdev1.fast.ai](https://nbdev1.fast.ai). You can use version-pinning
-in your `requirements.txt` or `settings.ini` (i.e use `'nbdev<2'` as
-your dependency) to stop nbdev from being upgraded.**
+*NB: This is nbdev v2, a major upgrade of nbdev. Whilst the differences
+to nbdev1 aren’t huge, it does require some changes. The old version
+docs are at [nbdev1.fast.ai](https://nbdev1.fast.ai). You can use
+version-pinning in `settings.ini` (i.e `'nbdev<2'`) to stop nbdev from
+upgrading. To upgrade, follow the [migration
+tutorial](/migrating.html).*
 
 ------------------------------------------------------------------------
 
@@ -68,8 +67,17 @@ The best way to learn to use nbdev is to complete one of these tutorials
 square in the bottom right of the video; to view in a separate Youtube
 window, click the Youtube logo):
 
-<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/l7zS8Ld4_iA" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen>
-</iframe>
+<div>
+
+<div>
+
+<a href="http://www.youtube.com/watch?v=l7zS8Ld4_iA" target="_blank"
+title="nbdev walkthrough"><img
+src="https://github.com/fastai/logos/raw/main/nbdev_walkthrough.png" /></a>
+
+</div>
+
+</div>
 
 (There’s an [alternate version of the
 walkthru](https://youtu.be/67FdzLSt4aA) avaialable with the coding
@@ -103,6 +111,7 @@ available commands:
     nbdev_preview                   Start a local docs webserver
     nbdev_pypi                      Create and upload Python package to PyPI
     nbdev_quarto                    Create Quarto docs and README.md
+    nbdev_readme                    Render README.md from index.ipynb
     nbdev_release                   Release both conda and PyPI packages
     nbdev_sidebar                   Create sidebar.yml
     nbdev_test                      Test in parallel notebooks matching `fname`, passing along `flags`

nbs/getting_started.ipynb

@@ -79,7 +79,22 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "<iframe width=\"560\" height=\"315\" src=\"https://www.youtube-nocookie.com/embed/l7zS8Ld4_iA\" frameborder=\"0\" allow=\"accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture\" allowfullscreen></iframe>"
+    "::: {.content-visible when-format=\"html\"}\n",
+    "\n",
+    "<iframe width=\"560\" height=\"315\" src=\"https://www.youtube-nocookie.com/embed/l7zS8Ld4_iA\" frameborder=\"0\" allow=\"accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture\" allowfullscreen></iframe>\n",
+    "\n",
+    ":::"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "::: {.content-visible when-format=\"markdown\"}\n",
+    "\n",
+    "[![](https://github.com/fastai/logos/raw/main/nbdev_walkthrough.png)](http://www.youtube.com/watch?v=l7zS8Ld4_iA \"nbdev walkthrough\"){target=\"_blank\"}\n",
+    "\n",
+    ":::"
    ]
   },
   {
@@ -120,6 +135,7 @@
       "\u001b[1m\u001b[94mnbdev_preview\u001b[0m                   Start a local docs webserver\n",
       "\u001b[1m\u001b[94mnbdev_pypi\u001b[0m                      Create and upload Python package to PyPI\n",
       "\u001b[1m\u001b[94mnbdev_quarto\u001b[0m                    Create Quarto docs and README.md\n",
+      "\u001b[1m\u001b[94mnbdev_readme\u001b[0m                    Render README.md from index.ipynb\n",
       "\u001b[1m\u001b[94mnbdev_release\u001b[0m                   Release both conda and PyPI packages\n",
       "\u001b[1m\u001b[94mnbdev_sidebar\u001b[0m                   Create sidebar.yml\n",
       "\u001b[1m\u001b[94mnbdev_test\u001b[0m                      Test in parallel notebooks matching `fname`, passing along `flags`\n",
@@ -132,6 +148,13 @@
     "!nbdev_help"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## FAQ"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -146,6 +169,25 @@
     "[Watch this video](https://youtu.be/9Q6sLbz37gk).  Don't worry, we still get this too, despite having used `nbdev` for a wide range of \"very serious\" software projects over the last three years, including [deep learning libraries](https://github.com/fastai/fastai), [API clients](https://github.com/fastai/ghapi), [Python language extensions](https://github.com/fastai/fastcore), [terminal user interfaces](https://github.com/nat/ghtop), and more!"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## nbdev in the wild\n",
+    "\n",
+    "### fastai ecosystem\n",
+    "\n",
+    "`nbdev` has been used to build innovative software in the fastai\n",
+    "ecosystem, including the [`fastai`](https://docs.fast.ai/) deep learning\n",
+    "library which implements a [unique layered API and callback\n",
+    "system](https://arxiv.org/abs/2002.04688), and\n",
+    "[`fastcore`](https://fastcore.fast.ai/), which supercharges Python\n",
+    "leveraging its dynamic nature. Furthermore, `nbdev` allows a very small\n",
+    "number of developers to maintain and grow a [large\n",
+    "ecosystem](https://github.com/fastai) of software engineering, data\n",
+    "science, machine learning, and devops tools."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},