Tutorial

First steps

Install Nbdev by with the following command –> add Nbdev

This will install Nbdev in your global environment.

Create a directory in your local system where you would want to start your work. For example, in your local system

cd into this directory now. This will be the place where you are going to place your project. Now open a command prompt from inside this directory and type julia, this will launch a Julia shell. Here type ] to launch the "pkg" prompt and then you can type activate . in order to create a restricted environment where you can restrict further installations or else you can skip typing activate . and type import Nbdev followed by Nbdev.new(). This will create the "docs", "Nbdev", "nbs" and "src" directories in your project root. In addition to these directories the "Manifest.toml", mkdocs.yml" and "Project.toml" will also be created at the project root.

Note

Right now nbdev is highly opinionated about the folder structure like presence of "nbs", "src" and "docs" directory.

First notebook

Inside the project directory, open a terminal and start Pluto the usual way and create a notebook inside the "nbs" directory.

At this point you might have installed Nbdev in your global environment. If this is not the case then follow any of the below methods.

Start building your project

There are some anchors which tell Nbdev about the portion of your notebook that should be exported as code or should be part of documentation or should not be touched.

#export

when you put the comment #export at the begining of a cell, it tells nbdev to export that cell as a code into the source file.

#export
function somefunc(x)
    x+1
end

Nbdev will now put the above cell as part of the source file (with the same name as the current notebook) inside the src directory.

#hide

Suppose that you have included soem cells as par of experment while developing your package but you want that the cell should neither be exported as a code nor that should be exported as part of documentation.

In such a case use the #hide anchor at the begining of the cell.

#hide
myexperiment = 1+1

such a cell won't be exported.

Any other cell which neither has the #hide nor the #export anchor, is exported as an example block. For such a block the cell is executed and the output is captured.

The output and the code of an example cell appears in the final document.

#noop

Nbdev captures the output for cells which are not marked with #export by default. but there might be times when you have an example for which you just want to show the code and not the output. Such cases can be handled by the #noop anchor. Just start such cells with #noop and nbdev will not capture output for such cells.

begin
#noop
"
some experiment
"
function myexperiment
    1+1
end
myexperiment
end

In the above case even though Pluto displays the docstring as an output, that output won't be displayed in your document.

As another example let's consider something like the code below

#noop add = 1+1 add`

The output for such code cell won't be captured in the documentation. Only the code will be displayed once you build the document.

Docstrings

Define a docstring for functions, structs etc. and use the special function showDoc to document that function or struct

"""
> This is a function docstring
""" 
function somefunc()
    1+1
end
------
Output
------
<div class="pluto-docs-binding">
<span>somefunc</span>
<div class="markdown"><blockquote>
<p>This is a function docstring</p>
</blockquote>


</div>
</div>

showdoc(somefunc) would show the function like this 👇

showdoc(somefunc)

Exporting code

Once you are done with your notebook and you can run notebook2script(). This reads the current notebook in the "nbs" folder, scrubs out all the cells which are do not start with #export and creates a module file in the src folder.

The module file in the src folder will have the same name as the current file with the first letter in uppercase.

The exported code file automatically has all the code inside the module with the same name as the file.

For example, the exported source code file would have the following structure 👇

module Example

function somefunc(x)
    x+1
end

end

Once you are happy with the code you can export the source code by calling

notebook2script(nbsdir, srcdir)

Here "nbsdir" is the directory where your notebooks are stored and the "srcdir" is the directory where you want your source code files to be exported. This is usually the src directory.

Tests

Nbdev comes with support for PlutoTests(in alpha) out of the box.

What this means is that you can write reactive tests within the same notebook where you are writing your code. when you run that particular notebook, the affected tests are executed. So, you can write tests as you write your code.

In addition to reactivity you can also take advantage of other goodies in PlutoTests like "time travel" to see the different stages of your code (follow the link to PlutoTests for further details).

Note

Currently PlutoTests is in alpha so use it with caution. However, you can even use the native test suite in Julia to write your tests but won't get features like time travel while using the native test suite.

Automatic execution of tests using github actions or Travis CI is planned for future versions of PlutoTest

Building documentation

Do not forget to edit the "index" notebook available in the "nbs" folder. This notebook would be used as your homepage and the contents of this notebook are also used in the README file.

Note

You will get the index notebook in the nbs directory when you create a new project using the nbdev template.

To build documentation, goto the project root and launch the Julia prompt and then import Nbdev with import Nbdev and then call the following function Nbdev.build(<your notebook directory). Your code at the Julia prompt should look like this

import Nbdev
Nbdev.build("nbs")

This will run all your notebooks in the notebook directory (/nbs usually) and pick up the cells which are not marked as #export or #hide and then create markdown files in the /docs directory.

Creating the Table of contents

The default configuration in the "mkdocs.yml" file (available to you when you create your repository from the template) contains all the necessary default configuration required to create you project page.

In order to test how your website looks like, go to the project root and type mkdocs serve . This would serve the project documentation to view locally (localhost).

The table of contents in the default case would be created by mkdocs on the basis of the documents available under the "docs" directory.

If you want to give your own spin to the table of contents then add a config similar to the following in the mkdocs.yml file–>

nav:
    - Home: index.md
    - Docs:
      - Nav1: nav1.md
      - Nav2: nav2.md

Note

Make sure that the "Home" navigation should always be the index.md file

For more details about setting up navigation refer this and this

Other required edits

In the mkdocs.yml file, edit the "sitename" config to the name that you want to give to your site. The "repourl" and "repo_name" should be your git repository url and the name of your git repository respectively.

Optional edits

There are loads of other optional edits which you can make to the config file in order to customize your project website. Refer the documentation here to know about the other options.

Publishing your project website

The first step is to checkin all your project contents to your repoitory. As soon as you push your changes to the remote branch, the github action (placed under "/.github/workflows" creates a new "gh-pages" branch under your project repository, builds the project webpages and pushes the created pages to the ""gh-pages" branch.

If you go to the "Actions" tab in your github repository then you can view the Action under the "All workflows" section. Here, a green tick mark before the action name suggests that all went fine.

Now, go to the Settings tab in your repository, click on Pages menu item from the left menu and in the "Source" drop-down select "gh-pages" as the source and root as the source folder, Click on save.

A detailed step by step description about configuring github pages can be read here.

You project website would be published at the following url –> "<username>.github.io/<project reporsitory name>"