Placeholders

Since most urnc commands accept directories as input, it is crucial to have a flexible mechanism for specifying output paths. Urnc provides this functionality through a set of placeholder variables, which can be used to define output paths in commands or configuration files. The supported placeholders are listed in section Placeholder Variables.

Placeholder Variables

nb.abspath Absolute path to the input notebook.
nb.absdirpath Absolute path to the directory containing the notebook.
nb.rootpath Absolute path to the root directory of the notebook.
nb.relpath Relative path to the notebook from the root directory.
nb.reldirpath Relative path to the directory containing the notebook from the root directory.
nb.name Name of the notebook including extension.
nb.basename Name of the notebook without extension.
nb.ext Extension of the notebook without the dot.

Example

For a input notebook located at C:/temp/mycourse/lectures/lecture1.ipynb, the following placeholders would be available for constructing the output path:

nb.abspath    = "C:/temp/mycourse/lectures/lecture1.ipynb"
nb.absdirpath = "C:/temp/mycourse/lectures"
nb.rootpath   = "C:/temp/mycourse"
nb.relpath    = "lectures/lecture1.ipynb"
nb.reldirpath = "lectures"
nb.name       = "lecture1.ipynb"
nb.basename   = "lecture1"
nb.ext        = "ipynb"

Motivation

Consider the following course structure::

C:/temp/mycourse-admin
├── config.yaml
├── lectures
│   └── week1
│       ├── lecture1.ipynb
│       └── lecture2.ipynb
└── assignments
    └── week1.ipynb

Now assume we want to create a public version of our course, containing two versions of each notebook. One version without solutions (for presentation during the lecture) and one version with solutions (to be released one week later). Two possible output structures are shown below:

C:/temp/variant1                       C:/temp/variant2
├── lectures                           ├── lectures
│   └── week1                          │   ├── week1
│       ├── lecture1.ipynb             │   │   ├── lecture1.ipynb
│       ├── lecture1-solution.ipynb    │   │   └── lecture2.ipynb
│       ├── lecture2.ipynb             │   └── week1-solutions
│       └── lecture2-solution.ipynb    │       ├── lecture1.ipynb
└── assignments                        │       └── lecture2.ipynb
    └── week1.ipynb                    ├── assignments
    └── week1-solution.ipynb           │   └── week1.ipynb
                                       └── assignments-solutions
                                           └── week1.ipynb

Both of the above structures can be easily generated using the placeholder variables described above. For example, the following commands would create the above structures:

# Bash Syntax
out1='C:/temp/variant1/{nb.relpath}'
sol1='C:/temp/variant1/{nb.reldirpath}/{nb.basename}-solution.{nb.ext}'
out2='C:/temp/variant2/{nb.relpath}'
sol2='C:/temp/variant2/{nb.reldirpath}-solutions/{nb.basename}-solution.{n.ext}'
urnc convert --output=$out1 --solution=$sol1 C:/temp/mycourse
urnc convert --output=$out2 --solution=$sol2 C:/temp/mycourse

Using plain directory paths, the above commands could be written even shorter, as:

out1='C:/temp/variant1'
sol1='C:/temp/variant1'
out2='C:/temp/variant2'
sol2='C:/temp/variant2/{nb.reldirpath}-solutions/{nb.basename}-solution.{n.ext}'
urnc convert --output=$out1 --solution=$sol1 C:/temp/mycourse
urnc convert --output=$out2 --solution=$sol2 C:/temp/mycourse

Plain Directory Paths

To make specifying output paths less verbose, urnc also accepts “plain directory paths” as output paths. A path is considered a plain directory path if it does neither end with .ipynb nor contain any placeholders. If a plain directory path is provided, the notebooks will be stored inside that directory in the same subfolder they had in the original input directory. However, to avoid overwriting outputs of previous targets, each target will use a different file name for the notebooks in this case. The following rules apply:

Target	Naming Pattern
`student`	`{nb.reldirpath}/{nb.basename}.{nb.ext}`
`solution`	`{nb.reldirpath}/{nb.basename}-solution.{nb.ext}`
`execute`	`{nb.reldirpath}/{nb.basename}-executed.{nb.ext}`
`clear`	`{nb.reldirpath}/{nb.basename}-cleared.{nb.ext}`
`fix`	`{nb.reldirpath}/{nb.basename}-fixed.{nb.ext}`

Limitations

The placeholder variables nb.rootpath, nb.relpath and nb.reldirpath require the “root” [1] of the current course to be specified. Usually, this is done by searching the file system upwards from the given input path, until a config.yaml file is found. If no config.yaml file is found, the current working directory is considered the course root. This scenario could happen, e.g., if urnc convert is used on a single notebook outside a specific course.