Package: nbdev-steve
Welcome to nbdevCreate delightful python projects using Jupyter Notebooksnbdevis a library that allows you to develop a python library inJupyter Notebooks, putting all your code, tests and documentation in one place. That is: you now have a trueliterate programmingenvironment, as envisioned by Donald Knuth back in 1983!nbdevmakes debugging and refactoring your code much easier relative to traditional programming environments. Furthermore, using nbdev promotes software engineering best practices because tests and documentation are first class citizens.The developers use this regularly on macOS and Linux. We have not tested it on Windows and not all features may work correctly.Features of Nbdevnbdevprovides the following tools for developers:Automatically generate docsfrom Jupyter notebooks.  These docs are searchable and automatically hyperlinked to appropriate documentation pages by introspecting keywords you surround in backticks.Utilities toautomate the publishing of pypi and conda packagesincluding version number management.A robust,two-way sync between notebooks and source code, which allow you to use your IDE for code navigation or quick edits if desired.Fine-grained control on hiding/showing cells: you can choose to hide entire cells, just the output, or just the input.  Furthermore, you can embed cells in collapsible elements that are open or closed by default.Ability towrite tests directly in notebookswithout having to learn special APIs.  These tests get executed in parallel with a single CLI command.  You can even define certain groups of tests such that you don't have to always run long-running tests.Tools formerge/conflict resolutionwith notebooks in ahuman readable format.Continuous integration (CI) comes setup for you withGitHub Actionsout of the box, that will run tests automatically for you.  Even if you are not familiar with CI or GitHub Actions, this starts working right away for you without any manual intervention.Integration With GitHub Pages for docs hosting: nbdev allows you to easily host your documentation for free, using GitHub pages.Create Python modules, followingbest practices such as automatically defining__all__(more details) with your exported functions, classes, and variables.Math equation supportwith LaTeX.... and much more!  See theGetting Startedsection below for more information.A Motivating ExampleFor example, lets define a class that represents a playing card, with associated docs and tests in a Jupyter Notebook:In the above screenshot, we have code, tests and documentation in one context!nbdevrenders this into searchable docs (which are optionally hosted for free on GitHub Pages).  Below is an annotated screenshot of the generated docs for further explanation:The above illustration is a subset ofthis nbdev tutorial with a minimal example, which uses code fromThink Python 2by Allen Downey.Explanation of annotations:The headingCardcorresponds to the firstH1heading in a notebook with a note blockAPI Detailsas the summary.nbdevautomatically renders a Table of Contents for you.nbdevautomatically renders the signature of your class or function as a heading.The cells where your code is defined will be hidden and replaced by standardized documentation of your function, showing its name, arguments, docstring, and link to the source code on github.This part of docs is rendered automatically from the docstring.The rest of the notebook is rendered as usual.  You can hide entire cells, hide only cell input or hide only output by using theflags described on this page.nbdev supports special block quotes that render as colored boxes in the documentation.  You can read more about themhere.  In this specific example, we are using theNoteblock quote.Words you surround in backticks will be automatically hyperlinked to the associated documentation where appropriate. This is a trivial case whereCardclass is defined immediately above, however this works across pages and modules.  We will see another example of this in later steps.Installingnbdev is on PyPI and conda so you can just runpip install nbdevorconda install -c fastai nbdev.  Microsoft Windows users should usepipinstead ofcondato install nbdev.For aneditable install, use the following:git clone https://github.com/fastai/nbdev
pip install -e nbdevnbdev is tested to work on Ubuntu, Macos and Windows, for the versions tagged with the-latestsuffix inthese docs.Note thatnbdevmust be installed into the same python environment that you use for both your Jupyter Server and your workspace.Getting StartedThe following are helpful resources for getting started with nbdev:Thetutorial.Aminimal, end-to-end exampleof using nbdev.  We suggest replicating this example after reading through the tutorial to solidify your understanding.Thedocs.release notes.If Someone Tells You Should Not Use Notebooks For Software DevelopmentWatch this video.ContributingIf you want to contribute tonbdev, be sure to review thecontributions guidelines. This project adheres to fastai`scode of conduct. By participating, you are expected to uphold this code. In general, the fastai project strives to abide by generally accepted best practices in open-source software development.Make sure you have the git hooks we use installed by runningnbdev_install_git_hooksin the cloned repository folder.CopyrightCopyright 2019 onwards, fast.ai, Inc. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project's files except in compliance with the License. A copy of the License is provided in the LICENSE file in this repository.Appendixnbdev and fastainbdevhas been used to build innovative software used by many developers, such asfastai, a deep learning library which implements aunique layered api and callback system, andfastcore, an extension to the Python programming language. Furthermore,nbdevallows a very small number of developers to maintain and grow alarge ecosystemof software engineering, data science, machine learning and devops tools.Here, for instance, is howcombined_cosis defined and documented in thefastailibrary: