Questions on nbdev

I’ve a couple questions about nbdev and don’t know if there’s any separate thread to post these, so asking here:

  1. How can I export a cell to a specific module (other than default_exp)
  2. Any guidelines on customizing sidebar? what are naming conventions for notebooks?
  3. I want to have my custom tag for colab which will be used to remove those cells from notebook, since there are many Colab specific instructions I need to execute every session (Like script to install fastai2 and dependencies, cloning my repo, etc.), is there any similar functionality available in nbdev that I’m unaware of?

Be sure to look at the docs as all your answers are in there:

  1. #export/exports/exporti module_name
  2. Edit the sidebar.json in the docs folder. Look at fastai2 for some examples on how things are done. Notebooks should be named with the module names they create if you want the automatic linking with entity between ` to work.
  3. #hide remove cells from notebooks for documentation.
2 Likes

Do the numbers at the beginning are ignored?

But they remain in the notebook. I want them to be removed from notebook itself since those are platform specific instructions

I did. in fact, I was trying to replicate that for a while but wasn’t able to have everything as expected. Here’s my sidebar.json

{
  "Overview": "/",
  "Tutorial": {
    "Overview":"/tutorial",
    "Explore Architectures": "/tutorial.arch_explore"      
  },
  "Core": "/core"
}

and this is generated doc Core and Overview is not working

Yes the numbers at the beginning are always ignored.

If you want cells removed from a notebook… remove them before committing. There is no mechanism in nbdev to do this since the goal is to share the notebook.

For the sidebar, look more closely at the fastai2 sidebar.json. As soon as you have subcategories, you need something in each of your main categories to please Jekyll, so

{
  "Getting started": {
    "Overview": "/"
  },
  "Tutorial": {
    "Overview":"/tutorial",
    "Explore Architectures": "/tutorial.arch_explore"      
  },
  "Core": "/core" --> also needs something inside.
}
2 Likes

This is an ignorant question, but here goes: I forked someone else’s Python package by creating a Github repository that I had set up using the nbdev template. On my local machine, I created a repository in a subdirectory of a folder that I had also set up using nbdev (more or less by mistake). When I push a commit from my local machine to my Github repository, the author of the commit shows as ‘Jeremy Howard’. Yet I can’t find any mention of him, and ‘author’ is set to my name in ‘settings.ini’. Does anyone know what’s going on? I also live in fear of committing to nbdev itself by accident. Is there some hidden nbdev settings file that I don’t know about?

How to update index.ipynb from README.md ?

CI step Check if all notebooks are cleaned always fails:

Process exits abruptly with following output

  echo "Check we are starting with clean git checkout"
  if [ -n "$(git status -uno -s)" ]; then echo "git status is not clean"; false; fi
  echo "Trying to strip out notebooks"
  nbdev_clean_nbs
  echo "Check that strip out was unnecessary"
  git status -s # display the status to see which nbs need cleaning up
  if [ -n "$(git status -uno -s)" ]; then echo -e "!!! Detected unstripped out notebooks\n!!!Remember to run nbdev_install_git_hooks"; false; fi
  shell: /bin/bash -e {0}
  env:
    pythonLocation: /opt/hostedtoolcache/Python/3.6.10/x64
Check we are starting with clean git checkout
git status is not clean
##[error]Process completed with exit code 1.

Link to the repository: https://github.com/Kshitij09/fast_impl

I realized what was wrong. I forgot to push changes in _nbdev.py :sweat_smile:

1 Like

Is it possible to propograte README.md changes to index.ipynb? Just like we do with library changes to notebook (script2notebook).

I prefer writing markdown pages with an editor rather than putting it in a notebook.

Also, is it possible to have different PyPi package description and repository’s README ?

I figured out the answer to my own question, which was kind of obvious: Github uses your email to assign your name to a commit. When I set up my cloud VM, I forgot to change the github email and so when I created a project using the nbdev template, the associated email was “info@fast.ai,” which is linked to Jeremy Howard’s name. To fix it:

    git config --global user.email  # See what email is being used now
    git config --global user.email "email@example.com”  # Re-set it

@sgugger I’d like to suggest removing the default email from the nbdev template so Jeremy isn’t the default author of all commits…if that’s possible.

This information is not embedded in the template by itself, so there is no way to remove it. I guess GitHub puts that as a default if it doesn’t have another one because Jeremy was the one who created the template, but that’s just a guess.

OK thanks Sylvain. I don’t know if anyone else will be as dumb as I was, but it might be worth a line in the documentation like “Don’t forget to set your Github email address if creating a repository from an nbdev template on a VM.”

What can I do to apply nbdev_build_docs recursively on subdirectories ?