Helper Script to use nbdev remote theme

nbdev_jekyll.py

#!/usr/bin/env python
# coding: utf-8

from fastcore.all import *
from shutil import rmtree
import yaml

rm=['_includes','_layouts','css','fonts','js','licenses','tooltips.json','Gemfile','Gemfile.lock']
raw='https://raw.githubusercontent.com/fastai/nbdev_template/master/docs/'

def rm_files(pth:Path):
    "Removes files controlled by theme"
    for f in rm:
        p = pth/f'{f}'
        if p.is_dir(): rmtree(p, ignore_errors=True)
        elif p.is_file() and p.exists(): p.unlink()
    urlsave(f'{raw}Gemfile', dest=str((pth/'Gemfile')))
    urlsave(f'{raw}Gemfile.lock', dest=str((pth/'Gemfile.lock')))

def config(pth:Path):
    """Edit config file to include remote theme."""
    p = pth/'_config.yml'
    cfg = yaml.safe_load(p.read_text())
    cfg.pop('theme', None)
    cfg['plugins'] = ['jekyll-remote-theme']
    cfg['remote_theme']= 'fastai/nbdev-jekyll-theme'
    p.write_text(yaml.safe_dump(cfg))


@call_parse
def use_theme(docs_dir:Param('nbdev docs directory', str)='docs'):
    pth = Path(docs_dir)
    assert pth.exists(), f'Could not find directory: {pth.absolute()}'
    rm_files(pth)
    config(pth)

Background

We recently modified nbdev to use a custom Jekyll theme instead of vendoring all the HTML, CSS and Javascript files. This allows us to maintain the front-end pieces in a better way, and provide a mechanism for pushing updates and bug fixes to everyone.

For those with existing nbdev projects, we recommend using this script (instructions below) in order to transition to using the nbdev-jekyll-theme.

Instructions on how to use

Step 0: Make sure you are using the latest version of nbdev

pip install -U nbdev

Step 1: Download Script

For easiest use, download this script into the root of your nbdev directory

wget https://gist.githubusercontent.com/hamelsmu/977e82a23dcd8dcff9058079cb4a8f18/raw/3f5a7f74b4deee2b364cfb1e0d6d38abc795b9f4/nbdev_jekyll.py

Step 2: Run Script

From the root of your nbdev directory run the script, this assumes that your docs are contained in a docs/ directory.

python nbdev_jekyll.py

If your nbdev docs are contained in a different folder, such as docs_src, you can pass an argument to change the directory like so:

python nbdev_jekyll.py --docs_dir docs_src

Step 3: Install New Jekyll Gems

If you wish to preview the docs locally, you may require new Ruby Gems for the Jekyll theme to work. You can accomplish this by chaning into your docs directory:

cd docs

And running the following command:

bundle install

Step 4: Preview your nbdev docs

You can either:

• Run make docs_serve from the root of your nbdev repo (recommended) OR
• Run bundle exec jekyll serve from the docs/ directory

Hi Hamel, I think the link the the nbdev_jekyll.py script needs to be updated. I tried running that version on my Ubuntu machine and got the following error:

Traceback (most recent call last):
  File "nbdev_jekyll.py", line 31, in <module>
    def use_theme(docs_dir:Param('nbdev docs directory', str)='docs'):
  File "/usr/local/lib/python3.6/dist-packages/fastcore/script.py", line 110, in call_parse
    return _f()
  File "/usr/local/lib/python3.6/dist-packages/fastcore/script.py", line 105, in _f
    tfunc(**merge(args, args_from_prog(func, xtra)))
  File "nbdev_jekyll.py", line 34, in use_theme
    rm_files(pth)
  File "nbdev_jekyll.py", line 16, in rm_files
    elif p.is_file(): p.unlink(missing_ok=True)
TypeError: unlink() got an unexpected keyword argument 'missing_ok'

Updating the the current raw version gave me no problem: https://gist.githubusercontent.com/hamelsmu/977e82a23dcd8dcff9058079cb4a8f18/raw/3f5a7f74b4deee2b364cfb1e0d6d38abc795b9f4/nbdev_jekyll.py

@lewtun - I updated it, thanks!

Hi @hamelsmu! Maybe the config file needs to be updated in the current nbdev template?

Starting from the current template at fastai/nbdev_template@521d57f and trying to serve docs locally, I get a very similar error to https://forums.fast.ai/t/docs-rendering-as-raw-html-unsure-how-to-debug/90625 (Build Warning: Layout 'page' requested in *.html does not exist.)

Running this gist solved the issue (after commenting out rm_files line due to fastai/nbdev_template#75 (comment)).