Skip to content

Tutorial

First steps

Use this template to create a new repository. This will create a repository with the directory structure required for nbdev.

Note

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

Tip

Refer to this link to understand how to use a template repository.

First notebook

As a first steps clone your repository to your local machine.

Once you have cloned the repository, start Pluto the usual way as you use to do and create a notebook inside the "nbs" directory.

Each Pluto notebook maintains it's own environment. You can directly import a package and Pluto will install it from the registry. However, in our case Nbdev.jl is not yet registered. So, you can install Nbdev in the following way

In the first cell of your notebook type in the following code πŸ‘‡

using Nbdev

This will install Nbdev in our notebook environment.

Note

If you don't want to install Nbdev as part of every notebook that you create in your project, then you can follow the other options to install packages for your notebook projects by following the instructions in the Pluto wiki.

Start building your project

There are some anchors which tell Nbdev about which portion of your notebook should be exported as code, which portion should be part of documentation and which portion 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 docstrign 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" style="margin: .5em; padding: 1em; background: #8383830a; border-radius: 1em;">
<span style="
    display: inline-block;
    transform: translate(-19px, -16px);
    font-family: 'JuliaMono', monospace;
    font-size: .9rem;
    font-weight: 700;
    /* height: 1px; */
    margin-top: -1em;
    background: white;
    padding: 4px;
    border-radius: 7px;
    /* color: #646464; */
    /* border: 3px solid #f99b1536;
">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 f 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>"