nbdev
nbdev copied to clipboard
Add a CONTRIBUTING.md to `nbdev_new` output
It may be helpful for open-source projects adopting nbdev to have default CONTRIBUTING guidelines to work from, something like the following (derived from https://github.com/fastai/fastcore/blob/master/CONTRIBUTING.md, https://github.com/fastai/fastai/blob/master/README.md, and https://github.com/fastai/fastai/blob/master/CONTRIBUTING.md), with appropriate substitutions made for nbs_path
and any other such references.
How to contribute
This project is developed using nbdev, a way to create delightful software with Jupyter notebooks. The Python library and docs are automatically created from the notebooks in the /nbs
directory.
How to get started
Before anything else, please install the git hooks that run automatic scripts during each commit and merge to strip the notebooks of superfluous metadata (and avoid merge conflicts). After cloning the repository, run this command inside it: nbdev_install_hooks
How to submit notebook PRs
After making changes to the /nbs
notebooks, you should run nbdev_prepare and make any necessary changes in order to pass all the tests.
(You may also make limited changes directly to the .py
files in the library, in which case you should sync those changes back to the notebooks with nbdev_update.)
Do you want to contribute to the documentation?
- Docs are automatically created from the notebooks in the
/nbs
folder. - You can preview the docs locally by running nbdev_preview. While in preview mode, you can make updates to notebooks and they will be reflected (after a small delay) in your browser.
@hugetim i want to work on this
i want to work on this
I don't have plans to work on it myself, so that would be great! Thanks in advance.
@hugetim correct me if i am wrong there is already a contributing.md file exists for fastai/nbdev do you want to add it for fastai/nbdev/nbdev
Well, kind of. I want the nbdev_new command to generate one for you as part of the project files it creates for a new repo. Basically, I want to add it for fastai/nbdev_template.
One thing that should be added to my template above: an instruction to install nbdev. It can link to: https://nbdev.fast.ai/tutorials/tutorial.html#installation
Additionally, we should spell out the steps to take inside the project directory:
- Install jupyter notebook
- Install nbdev
- Install quarto
- Install hooks
- nbdev_export
- pip install -e '.[dev]'
- After making changes, run nbdev_prepare
Here's what I'm using for my project: https://github.com/hugetim/nbstata/blob/master/CONTRIBUTING.md
Seems relevant: #1103 - Deprecate nbdev-template and bring its files & functionality into nbdev
It may make more sense to do this as a notebook which generates CONTRIBUTING.md.
Also relevant: https://github.com/fastai/nbdev/issues/1021 - How to guide for developing nbdev