NotebookManagementTools.jl

NotebookManagementTools — Module

NotebookManagementTools

Module providing tools for generating markdown from Literate.jl-compliant julia scripts, after testing those scripts.

Intended to facilitate the separate execution and generation of notebooks that are part of a larger Documenter.jl documentation deployment. In this scenario, notebook "ground truth" is always a julia script (with Literate.jl-compatible narrative). Furthermore, when used with appropriate continuous integration workflows, notebooks can be generated on a need-to basis, to speed up document generation and the development of new tutorials.

The kind of repository we have in mind will be structured using Julia's "workspace" package management structure. For a stand-alone collection of tutorials following Julia's workspace package pattern, this might look something like this:

├── Project.toml     # <---- root project
├── docs
│   ├── make.jl
│   ├── Project.toml # <--- project for generating documentation wrapping the notebooks
│   └── src
│       └── notebooks
│           ├── tutorial1
│           │   ├── Project.toml  # <--- tutorial-specific project
│           │   ├── runtests.jl
│           │   └── notebook.jl
│           └── tutorial2
│               ├── Project.toml
│               ├── runtests.jl
│               ├── notebook.jl
│               └── notebook.md

Note

If you are not using Julia 1.12 or higher with a workspace project structure, you will need to explicitly add Literate to each notebook's project.

Tools

generate: The main tool, used to generate markdown from annotated julia script.
dirs: Used in continuous integration to list tutorial directories.
dirs_containing: Used in continuous integration to find tutorial directories containing files known to have changed in a pull-request.

Advanced Tools

set_path_to_literate: For pointing the generator to a version of Literate.jl different from the one in the NotebookManagementTools project.
path_to_literate: For inspecting the above.

source

NotebookManagementTools.set_path_to_literate — Function

set_path_to_literate(path)

Point TutorialsTools to the location of a directory containing a Project.toml file with a [deps] entry for "Literate". Typically, this is the absolute path to a repository "docs" directory.

julia> pwd()
"/Users/anthony/GoogleDrive/Julia/ClassImbalanceTutorials.jl"

julia> set_path_to_literate("~/GoogleDrive/Julia/ClassImbalanceTutorials.jl/docs/")

Use path_to_literate() to inspect the path once set.

source

NotebookManagementTools.path_to_literate — Function

path_to_literate()

Return the path to a Project.toml file with a [deps] entry for "Literate". Use set_path_to_literate to set or change.

source

NotebookManagementTools.generate — Function

generate(notebook_dir, path_to_literate=path_to_literate(); tests=true)

Attempt to generate a new markdown file from the file named "notebook.jl" and contained in notebook_dir, using Literate.jl and the project at notebook_dir, after activating and instantiating the Julia project in notebook_dir. A version of Literate.jl is used consistent with the project specified at path_to_literate (which is pushed to LOAD_PATH to make it available).

Literate.jl executes all code cells and wraps the input cell in regular julia fencing. In that way, when the markdown is included in a Documenter.jl project, no code is re-executed.

Testing

If tests==true, then, before attempting markdown generation, run, in a new Julia process, the code appearing in the file "runtests.jl" appearing in the directory notebook_dir, which should additionally contain the julia script notebook.jl.

Note

The test file runtests.jl should begin with "using Test; include("notebook.jl")" and end with "true".

Return value

Returns the path to the generated markdown, unless the Julia process exits abnormally, in which case an empty string is returned.

source

generate(notebook_dirs::AbstractVector, path_to_literate=path_to_literate(); tests=true)

Attempts to generate each notebook with directory in the provided list notebook_dirs. Returns paths to re-generated markdown files, or nothing if there is a failed notebook test or markdown generation failure.

source

NotebookManagementTools.dirs — Function

dirs(; root=pwd())

Return all top-level subdirectories of root as full paths.

source

NotebookManagementTools.dirs_containing — Function

dirs_containing([paths]; root=pwd())

Return, as full paths, a list of those top-level subdirectores of root that contain one or more of the full paths specified by paths.

shell> pwd
/Users/anthony/GoogleDrive/Julia/MLJ/StatisticalMeasures

shell> tree -L 2
.
├── docs
│   ├── build
│   ├── make.jl
│   ├── Project.toml
│   └── src
├── LICENSE
├── Project.toml
├── README.md
├── src
│   ├── confusion_matrices.jl
│   ├── continuous.jl
    ├── tools.jl
│   ├── docstrings.jl
│   └── unfussy.jl
└── test
    ├── confusion_matrices.jl
    ├── continuous.jl
    └── tools.jl

julia> paths = [joinpath(pwd(), "src", "confusion_matrices.jl"),];
julia> dirs_containing(paths)
1-element Vector{String}:
 "/Users/anthony/GoogleDrive/Julia/MLJ/StatisticalMeasures/src"

source