Following the Minimal end-to-end example of creating a nbdev project from scratch.
There is also a tutorial for completing an entire nbdev-based project from start to finish utilizing only Google Colaboratory which is a free alternative Jupyter environment with GPU capabilities. (There is also a Colab Pro option).
- Use the nbdev_template provided by fastai at https://github.com/fastai/nbdev_template to create a new repository.
- Add a description of the project
- Public repo
- Modify configuration files
settings.iniwhich are required for hosting documentation on GitHub Pages.
Go the the GutHub Pages settings and edit the
Sourceto build the GitHub Pages site from the
/docsfolder of the
masterbranch. While the message might indicate that the site is published, it won’t actually be there yet as the index.html file has yet to be created.
Clone the repo
git clone https://github.com/user/deck_of_cards.git
cdinto the repo
Install nbdev if not already installed.
- Write code into a Jupyter notebook
(When copying and pasting code from python files into a Jupyter notebook, copy the whole file into a single cell, then use
ctrl-shift-minus to split the code into separate cells.)
- Export to modules flag
If the following code is placed in the first cell,
#default_exp card, the argument
cardmeans that the code exported from the notebook will be placed in the destination
nbdev uses special comments, or flags, as a markup language that allows you to control various aspects of the docs and how code is exported to modules, and how code is tested.
#hidethis comment instructs nbdev to hide a cell when generating the docs.
#exportinstructs nbdev to export a cell to the appropriate python file. Without any argument this will default to the module specified by
Documentation and Tests
nbdev docs, tests and source codes can be organised into a single context.
- markdown cells for documentation
- assert statements can be used for testing
- nbdev has a Continuous Integration system.
- Edit the
nbdevrepositories require a notebook named
index.ipynbwhich is included in the repository when using the template.
index.ipynbwill become both the
README.mdfor the repo as well as the home page
index.htmlfor the documention.
The first cell of the index.ipynb template contains the following code:
#hide from your_lib.core import *`
This should be commented out or removed until the module being created is finished and then it can be replaced with the appropriate import statement.
nbdev_build_libfrom the root of the repo. This converts Jupyter notebooks to source code. Notebook cells tagged with
#exportwill be exported to the appropriate python module.
00_cards.ipynbgets converted to
nbdev_test_nbsto run the code and tests in all the notebooks.
To preview the docs run the command
make docs_servefrom the root of the repo. To do this you need to have jekyll / rubygems installed. This runs the CLI command
nbdev_build_docsfor you and allows you to preview the docs locally. For now I will just run this
nbdev_build_docscommand from the terminal in the root of the repo.
The first H1 heading in the index.ipynb file becomes a heading while the note block
API Detailsbecomes the summary.
nbdev automatically renders a table of content (based on markdown headings).
nbdev renders the signature of a class or function as a heading.
nbdev adds a link to the corresponding source code with the command
Docstrings in functions / classes is also rendered as markdown documentation.
The rest of the notebook is rendered by converting the markdown into HTML and will show inputs and outputs of cells including plots etc. Flags can be used to hide entire cells, hide cell input or output using.
nbdev supports special block quotes that will be rendered as coloured boxes in the documentation.
Words surrounded by backticks will automatically be hyperlinked to the associated documentation where appropriate.
After editing the docs run
nbdev_build_docsto re-render them.
git add .
git commit -m"commit message"
Pushing to GitHub automatically triggers continuous integration using GitHub Actions.
- After the files are pushed to GitHub it will rebuild the docs automatically.
- GitHub Pages needs to be enabled for the site to be published. The colour background will change from blue (ready to be published) to green when the page has been built. Click the URL (also in the About / Website setting of the repo page) to go to the URL of the page.