Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

How to guide for developing nbdev #1021

Open
tylere opened this issue Sep 8, 2022 · 6 comments
Open

How to guide for developing nbdev #1021

tylere opened this issue Sep 8, 2022 · 6 comments
Labels
documentation Improvements or additions to documentation

Comments

@tylere
Copy link
Contributor

tylere commented Sep 8, 2022

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}
    
@seeM seeM added the documentation Improvements or additions to documentation label Sep 8, 2022
@jph00 jph00 changed the title How to guide for running prerelease library versions How to guide for developing nbdev Sep 9, 2022
@jph00
Copy link
Member

jph00 commented Sep 9, 2022

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
Copy link
Member

jph00 commented Sep 9, 2022

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
Copy link
Member

jph00 commented Sep 15, 2022

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
Copy link

dmose commented Nov 28, 2022

@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
Copy link

dmose commented Nov 29, 2022

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
Copy link
Member

jph00 commented Dec 3, 2022

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

4 participants