How to guide for developing nbdev

[tylere]

aka "runs with scissors"

Document how to develop and test with pre-release versions of nbdev and the primary dependencies (i.e. quarto, jupyter), all of which are actively being developed.

Some topics to potentially include:

• Describe how to preview locally using a prerelease version of nbdev (head or a particular commit)

  For example:

  pip install -U git+https://github.com/fastai/nbdev.git@08462b3da90c86a06cd62159babc69c346d21f88
  

• Describe how to deploy to GitHub using a prerelease version of nbdev and/or quarto

  workflows/deploy.yaml

  jobs:
    deploy:
      runs-on: ubuntu-latest
      steps:
        - uses: fastai/workflows/quarto-ghp@master
          with: {pre: 1}
  

[jph00]

I updated the title to make this a more general docs issue.

BTW our recommended way to develop is to git clone nbdev and then cd nbdev && pip install -e '.[dev]'.

[jph00]

Oh also we'd generally recommend also installing fastcore and execnb in this way too, since they're the key deps of nbdev and changes to them needed for nbdev are committed together. The core team all use a little script that does a git pull in each of nbdev, fastcore, and execnb when we start work, to ensure they're all up to date. Assuming that you used an editable install for each (pip install -e) then that'll mean you'll be using the latest versions of them.

[jph00]

In the nbdev development guide we might also want to touch on quarto development. @jjallaire kindly shared these recommended resources:

---

1. Read Pandoc Lua Filters to get familiar with the overall Pandoc programming model
2. Read Learn Lua in 15 Minutes for the quick and dirty "How do I do 'X' in Lua?"
3. Look at the code for some Pandoc filters
4. Look at the code for some Quarto extensions
5. Read the docs on Quarto extensions which provide Quarto specific bits + packaging.

---

...and he also shared some dev/debugging tips:

---

1. For interactive feedback, in v1.2 when you run quarto preview on a website any change to a filter will trigger a reload/re-render (so you'll see the modified behavior immediately in the browser). Bottom line is that changes to Lua files should result in an immediate re-render when running quarto preview.
2. If an error occurs you'll get a stack trace identifying the line of code where it failed in the preview terminal.
3. You can use the quarto.utils.dump() function to print a summary of any Pandoc object. For plain old println style debug output you can use the print() function.
4. If you switch the output format to "native" you'll see the Haskell native AST for the document (which allows you to see all transformations much more clearly than HTML output).

---

[dmose]

@jph00 Is this using a copy of pip installed by conda, or do the core devs not use conda?

conda/conda-build#4251 (comment) seems to suggest that one might want (using pip installed by conda):

pip install --no-build-isolation --no-deps -e '.dev'

but as I'm new to nbdev, I'm not particularly confident of that...

[dmose]

I wrote:

Is this using a copy of pip installed by conda, or do the core devs not use conda?

FWIW, this does seem to work.

[jph00]

Sorry @dmose I don't understand your question. The core devs do indeed use conda, except we use pip install -e for the libs we're working on directly. We use conda for pretty much everything else. I'm not sure what the --no-build-isolation --no-deps bit is for, but I don't use that myself.