Skip to content

Commit

Permalink
Merge pull request #836 from seeM/refactor-tutorial-first-edit
Browse files Browse the repository at this point in the history 
refactor tutorial: make your first edit
  • Loading branch information
@jph00
jph00 authored Aug 12, 2022
2 parents cadc59d + 7b78d61 commit dd5a0b1
Show file tree
Hide file tree
Showing 2 changed files with 156 additions and 35 deletions.
4 changes: 2 additions & 2 deletions nbdev/tutorial.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,12 @@
# %% auto 0
__all__ = ['say_hello', 'HelloSayer']

# %% ../nbs/tutorial.ipynb 62
# %% ../nbs/tutorial.ipynb 74
def say_hello(to):
"Say hello to somebody"
return f'Hello {to}!'

# %% ../nbs/tutorial.ipynb 86
# %% ../nbs/tutorial.ipynb 97
class HelloSayer:
"Say hello to `to` using `say_hello`"
def __init__(self, to): self.to = to
Expand Down
187 changes: 154 additions & 33 deletions nbs/tutorial.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,11 +56,11 @@
"source": [
"You'll need the following software to complete the tutorial, read on for specific installation instructions:\n",
"\n",
"- Python\n",
"- A Python package manager: we recommend conda or pip\n",
"- Jupyter Notebook\n",
"- nbdev\n",
"- Quarto\n",
"1. Python\n",
"2. A Python package manager: we recommend conda or pip\n",
"3. Jupyter Notebook\n",
"4. nbdev\n",
"5. Quarto\n",
"\n",
"If you haven't worked with Python before, we recommend getting started with the [Anaconda Individual Edition](https://www.anaconda.com/products/individual) and using the conda package manager."
]
Expand Down Expand Up @@ -303,9 +303,9 @@
"source": [
"nbdev provides the `nbdev_new` command to initialise an empty git repository. It'll infer information about your project from git and GitHub, and ask you to input anything remaining. It will create files in your repo that:\n",
"\n",
"- Streamline publishing Python packages to PyPI and conda\n",
"- Configure Quarto for publication-grade technical documentation\n",
"- Setup GitHub actions to test notebooks and build and deploy Quarto docs to GitHub pages"
"- Streamline publishing Python packages to PyPI and conda.\n",
"- Configure Quarto for publication-grade technical documentation.\n",
"- Setup GitHub actions to test notebooks and build and deploy Quarto docs to GitHub pages."
]
},
{
Expand All @@ -323,7 +323,25 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Commit and push all changes to GitHub:\n",
"It may ask you to enter information that it couldn't infer from git or GitHub."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"::: {.callout-note}\n",
"\n",
"`nbdev_new` assumes that your package name is the same as your repo name (with `-` replaced by `_`). Use the `--lib_name` option if that isn't the case.\n",
"\n",
":::"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Double-check your `settings.ini` file to ensure that it has all of the correct information. Then commit and push your additions to GitHub:\n",
"\n",
"```sh\n",
"git add .\n",
Expand Down Expand Up @@ -374,9 +392,9 @@
"What do these mean?\n",
"\n",
"- **CI** -- The CI (continuous integration) workflow streamlines your developer workflow, particularly with multiple collaborators. Every time you push to GitHub, it ensures that:\n",
" - Your notebooks and libraries are in sync\n",
" - Your notebooks are cleaned of unwanted metadata (which pollute pull requests and git histories and lead to merge conflicts)\n",
" - Your notebook tests all pass\n",
" - Your notebooks and libraries are in sync.\n",
" - Your notebooks are cleaned of unwanted metadata (which pollute pull requests and git histories and lead to merge conflicts).\n",
" - Your notebook tests all pass.\n",
"- **Deploy to GitHub Pages** -- Builds your docs with Quarto and deploys it to GitHub Pages."
]
},
Expand Down Expand Up @@ -461,6 +479,24 @@
"![](images/nbdev-hello-world-site-initial.png){fig-align=\"center\" .border .rounded .shadow-sm}"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Recap"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"You now have a base nbdev repo with continuous integration and hosted documentation! Here's a recap of the steps you took:\n",
"\n",
"- Create a GitHub repo.\n",
"- Initialise your repo with `nbdev_new`.\n",
"- Push to GitHub."
]
},
{
"cell_type": "markdown",
"metadata": {},
Expand All @@ -472,53 +508,140 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"### Edit settings.ini"
"In this section, you'll make your first edit to the repo you created in [_First steps_](#first-steps)."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Install hooks for git-friendly notebooks"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Next, edit the `settings.ini` file in your cloned repo. This file contains all the necessary information for when you'll be ready to package your library. The basic structure (that can be personalized provided you change the relevant information in `settings.ini`) is that the root of the repo will contain your notebooks, the `docs` folder will contain your auto-generated docs, and a folder with a name you select will contain your auto-generated modules."
"Step one when working with Jupyter notebooks in a new repo is to install nbdev's hooks (you can think of \"hooks\" as plugins or extensions to an application).\n",
"\n",
"Install them by entering this command in your terminal:\n",
"\n",
"```sh\n",
"nbdev_install_hooks\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Build and install lib"
"See [_Git-friendly Jupyter_](git_friendly_jupyter.html) for more about how nbdev hooks work and how to customise them. Here's a short summary:\n",
"\n",
"- Fix broken notebooks due to git merge conflicts so that they can be opened and resolved directly in Jupyter.\n",
"- Each time you save a Jupyter notebook, automatically clean unwanted metadata to remove unnecessary changes in pull requests and reduce the chance of git merge conflicts.\n",
"- Automatically trust notebooks in the repo so that you can view widgets from collaborators' commits. For this reason, **you should not install hooks into a repo you don't trust**."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now you can create your Python module. To do so, just run `nbdev_export` from the terminal at the root of your project folder, which builds the .py modules and library from the jupyter notebook.\n",
"::: {.callout-tip}\n",
"\n",
"nbdev hooks works on _any_ git repo, even if it doesn't use the broader nbdev system.\n",
"\n",
"Before you continue, you should ensure you have the latest version of your Python library and Quarto installed. Run `nbdev_install` to do an [editable install](https://stackoverflow.com/questions/35064426/when-would-the-e-editable-option-be-useful-with-pip-install) of your local Python library as well as fetch and install the latest version of Quarto. "
":::"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Install git and Jupyter hooks for git-friendly notebooks"
"### Install your package"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Jupyter Notebooks store additional metadata (like cell execution order) which cause challenges with git. `nbdev` makes working with notebooks becomes much easier. As a first step, run `nbdev_install_hooks` in the terminal from your project folder. This sets up a jupyter hook which remove metadata from your notebooks automatically, avoiding unnecessary file changes and greatly reducing the chance of a conflict. It also installs a git hook which attempts to resolve conflicts, and if any conflicts can't be resolved, places conflict markers into a notebook which you can fix directly in Jupyter.\n"
"You might have noticed that `nbdev_new` created a Python package in your repo. In our case, it was automatically named `nbdev_hello_world` by using our repo name `nbdev-hello-world` and replacing `-` with `_` to make it a valid Python package."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Start the Documentation Server\n",
"The next step is to install your package by entering this into your terminal:\n",
"\n",
"You can call `nbdev_preview` from the root of the repo to start the documentation server so you can see how your docs will render as you edit your notebooks. This is optional, but often useful especially if you are writing docs."
"```sh\n",
"pip install -e '.[dev]'\n",
"```\n",
"\n",
"This is the recommended way to make a Python package importable from anywhere in your current environment:\n",
"\n",
"- `-e` -- short for \"editable\", lets you immediately use changes made to your package during development.\n",
"- `.` -- refers to the current directory.\n",
"- `[dev]` -- includes \"development\" requirements: other packages that your notebooks use solely for documentation or testing."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Preview your docs"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"nbdev is an interactive programming environment that values fast feedback loops. The `nbdev_preview` command helps achieve this by using Quarto to render your docs on your computer and keep them updated as your edit your notebooks."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Start the preview by entering this into your terminal:\n",
"\n",
"```sh\n",
"nbdev_preview\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"It may say `Preparing to preview` for a few seconds while it gets started, and will eventually display something like:"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"```\n",
"Watching files for changes\n",
"Browse at http://localhost:3000/\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Click the link to open the preview in a new browser tab. It should look exactly like your online docs."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"::: {.callout-tip}\n",
"\n",
"We often find it useful to keep a preview window open on the side while we're editing our notebooks in Jupyter.\n",
"\n",
":::"
]
},
{
Expand Down Expand Up @@ -652,7 +775,7 @@
{
"data": {
"image/svg+xml": [
"<svg height=\"100\"><circle cx=\"50\" cy=\"50\" r=\"40\"/></svg>"
"<svg xmlns=\"http://www.w3.org/2000/svg\" height=\"100\"><circle cx=\"50\" cy=\"50\" r=\"40\"/></svg>"
],
"text/plain": [
"<IPython.core.display.SVG object>"
Expand All @@ -663,7 +786,7 @@
}
],
"source": [
"display(SVG('<svg height=\"100\"><circle cx=\"50\" cy=\"50\" r=\"40\"/></svg>'))"
"display(SVG('<svg height=\"100\" xmlns=\"http://www.w3.org/2000/svg\"><circle cx=\"50\" cy=\"50\" r=\"40\"/></svg>'))"
]
},
{
Expand Down Expand Up @@ -705,15 +828,6 @@
"You'll see that there's already a line there to import your library - change it to use the name you selected in `settings.ini`. Then, add information about how to use your module, including some examples. Remember, these examples should be actual notebook code cells with real outputs."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Preview the docs\n",
"\n",
"If you have not already, you should view your docs in fully rendered form to catch any mistakes. You can preview your documentation site with the command `nbdev_preview`. Note that your docs will build automatically in CI (discussed below)."
]
},
{
"cell_type": "markdown",
"metadata": {},
Expand Down Expand Up @@ -927,6 +1041,13 @@
"### Add links with backticks"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"[test](/read.html#helpers)"
]
},
{
"cell_type": "markdown",
"metadata": {},
Expand Down Expand Up @@ -1329,7 +1450,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"## Quarto Features\n",
"### Quarto Features\n",
"\n",
"nbdev supports most Quarto features. We encourage you to read the [Quarto documentation](https://quarto.org/) to discover all the features available to you. For example, this is how you can [incorporate mermaid charts](https://quarto.org/docs/authoring/diagrams.html):\n",
"\n",
Expand Down

0 comments on commit dd5a0b1

Please sign in to comment.