Package References

struct DemoPage <: Any
DemoPage(root::String)

Constructs a demo page object.

Fields

Besides the root path to the demo page folder root, this struct has some other fields:

• title: page title
• template: template content of the demo page.
• sections: demo sections found in root

Configuration

You can manage an extra config.json file to customize rendering of a demo page. Supported items are:

• order: specify the sections order. By default, it's case-insensitive alphabetic order.
• template: path to template filename. By default, it's "index.md". The content of the template file should has one and only one {{{democards}}}.
• theme: specify which card theme should be used to generate the index page. If not specified, it will default to nothing.
• stylesheet: relative path to the stylesheet file to override the default stylesheet provided by "theme".
• title: specify the title of this demo page. By default, it's the folder name of root. Will be override by template.
• properties: a dictionary of properties that can be propagated to its children items. The same properties in the children items, if exist, have higher priority.

The following is an example of config.json:

{
    "template": "template.md",
    "theme": "grid",
    "stylesheet": "assets/gridstyle.css",
    "order": [
        "basic",
        "advanced"
    ],
    "properties": {
        "notebook": "false",
        "julia": "1.6",
        "author": "Johnny Chen"
    }
}

Examples

The following is the simplest folder structure of a DemoPage:

demos
└── basic
    ├── demo_1.md
    ├── demo_2.md
    ├── demo_3.md
    ├── demo_4.md
    ├── demo_5.md
    ├── demo_6.md
    ├── demo_7.md
    └── demo_8.md

The following is a typical folder structure of a DemoPage:

demos
├── advanced
│   ├── advanced_demo_1.md
│   └── advanced_demo_2.md
├── basic
│   ├── part1
│   │   ├── basic_demo_1_1.md
│   │   └── basic_demo_1_2.md
│   └── part2
│       ├── config.json
│       ├── basic_demo_2_1.md
│       └── basic_demo_2_2.md
├── config.json
└── template.md

See also: MarkdownDemoCard, DemoSection

struct DemoSection <: Any
DemoSection(root::String)

Constructs a demo section that holds either nested subsections or demo cards.

Fields

Besides the root path to the demo section folder root, this struct has some other fields:

• cards: demo cards found in root
• subsections: nested subsections found in root

Configuration

You can manage an extra config.json file to customize rendering of a demo section. Supported items are:

• order: specify the cards order or subsections order. By default, it's case-insensitive alphabetic order.
• title: specify the title of this demo section. By default, it's the folder name of root.
• description: some header description that you want to add before demo cards.
• properties: a dictionary of properties that can be propagated to its children items. The same properties in the children items, if exist, have higher priority.

The following is an example of config.json:

{
    "title": "learn by examples",
    "description": "some one-line description can be useful.",
    "order": [
        "quickstart.md",
        "array.md"
    ],
    "properties": {
        "notebook": "false",
        "julia": "1.6",
        "author": "Johnny Chen"
    }
}

Examples

The following is the simplest folder structure of a DemoSection:

section
├── demo_1.md
├── demo_2.md
├── demo_3.md
├── demo_4.md
├── demo_5.md
├── demo_6.md
├── demo_7.md
└── demo_8.md

The following is a typical nested folder structure of a DemoSection:

section
├── config.json
├── part1
│   ├── demo_21.md
│   └── demo_22.md
└── part2
    ├── config.json
    ├── demo_23.md
    └── demo_24.md

See also: MarkdownDemoCard, DemoPage

struct JuliaDemoCard <: AbstractDemoCard
JuliaDemoCard(path::String)

Constructs a julia-format demo card from existing julia file path.

The julia file is written in Literate syntax.

Fields

Besides path, this struct has some other fields:

• path: path to the source julia file
• cover: path to the cover image
• id: cross-reference id
• title: one-line description of the demo card
• author: author(s) of this demo.
• date: the update date of this demo.
• description: multi-line description of the demo card
• julia: Julia version compatibility
• hidden: whether this card is shown in the generated index page
• notebook: enable or disable the jupyter notebook generation. Valid values are true or false.
• generate_cover whether to generate a cover image for this demo card by executing it
• execute: whether to execute the demo card when generating the notebook

Configuration

You can pass additional information by adding a YAML front matter to the julia file. Supported items are:

• cover: an URL or a relative path to the cover image. If not specified, it will use the first available image link, or all-white image if there's no image links.
• description: a multi-line description to this file, will be displayed when the demo card is hovered. By default it uses title.
• id: specify the id tag for cross-references. By default it's infered from the filename, e.g., simple_demo from simple demo.md.
• title: one-line description to this file, will be displayed under the cover image. By default, it's the name of the file (without extension).
• author: author name. If there are multiple authors, split them with semicolon ;.
• date: any string contents that can be passed to Dates.DateTime. For example, 2020-09-13.
• julia: Julia version compatibility. Any string that can be converted to VersionNumber
• hidden: whether this card is shown in the layout of index page. The default value is false.
• generate_cover whether to generate a cover image for this demo card by executing it. The default value is true. Note that execute must also be true for this to take effect.
• execute: whether to execute the demo card when generating the notebook. The default value is true.

An example of the front matter (note the leading #):

# ---
# title: passing extra information
# cover: cover.png
# id: non_ambiguious_id
# author: Jane Doe; John Roe
# date: 2020-01-31
# description: this demo shows how you can pass extra demo information to DemoCards package. All these are optional.
# julia: 1.0
# hidden: false
# ---

See also: MarkdownDemoCard, PlutoDemoCard, DemoSection, DemoPage

struct MarkdownDemoCard <: AbstractDemoCard
MarkdownDemoCard(path::String)

Constructs a markdown-format demo card from existing markdown file path.

Fields

Besides path, this struct has some other fields:

• path: path to the source markdown file
• cover: path to the cover image
• id: cross-reference id
• title: one-line description of the demo card
• author: author(s) of this demo.
• date: the update date of this demo.
• description: multi-line description of the demo card
• hidden: whether this card is shown in the generated index page

Configuration

You can pass additional information by adding a YAML front matter to the markdown file. Supported items are:

• cover: an URL or a relative path to the cover image. If not specified, it will use the first available image link, or all-white image if there's no image links.
• description: a multi-line description to this file, will be displayed when the demo card is hovered. By default it uses title.
• id: specify the id tag for cross-references. By default it's infered from the filename, e.g., simple_demo from simple demo.md.
• title: one-line description to this file, will be displayed under the cover image. By default, it's the name of the file (without extension).
• author: author name. If there are multiple authors, split them with semicolon ;.
• date: any string contents that can be passed to Dates.DateTime. For example, 2020-09-13.
• hidden: whether this card is shown in the layout of index page. The default value is false.

An example of the front matter:

---
title: passing extra information
cover: cover.png
id: non_ambiguious_id
author: Jane Doe; John Roe
date: 2020-01-31
description: this demo shows how you can pass extra demo information to DemoCards package. All these are optional.
hidden: false
---

See also: JuliaDemoCard, PlutoDemoCard, DemoSection, DemoPage

struct PlutoDemoCard <: AbstractDemoCard
PlutoDemoCard(path::AbstractString)

Constructs a pluto-format demo card from a pluto notebook path.

Fields

Besides path, this struct has some other fields:

• path: path to the source markdown file
• cover: path to the cover image
• id: cross-reference id
• title: one-line description of the demo card
• author: author(s) of this demo.
• date: the update date of this demo.
• description: multi-line description of the demo card
• julia: Julia version compatibility
• hidden: whether this card is shown in the generated index page

Configuration

You can pass additional information by adding a pluto front-matter section to the notebook. Supported items are:

• cover: an URL or a relative path to the cover image. If not specified, it will use the first available image link, or all-white image if there's no image links.
• description: a multi-line description to this file, will be displayed when the demo card is hovered. By default it uses title.
• id: specify the id tag for cross-references. By default it's infered from the filename, e.g., simple_demo from simple demo.jl.
• title: one-line description to this file, will be displayed under the cover image. By default, it's the name of the file (without extension).
• author: author name. If there are multiple authors, split them with semicolon ;.
• julia: Julia version compatibility. Any string that can be converted to VersionNumber
• date: any string contents that can be passed to Dates.DateTime. For example, 2020-09-13.
• hidden: whether this card is shown in the layout of index page. The default value is false.

An example of pluto front matter in the notebook:

#> [frontmatter]
#> title = "passing extra information"
#> cover = "cover.png"
#> id = "non_ambiguious_id"
#> author = "Jane Doe; John Roe"
#> date = "2020-01-31"
#> description = "this demo shows how you can pass extra demo information to DemoCards package. All these are optional."
#> julia: "1.0"
#> hidden: "false"

See also: MarkdownDemoCard, JuliaDemoCard, DemoSection, DemoPage

struct MarkdownDemoCard <: AbstractDemoCard
MarkdownDemoCard(path::String)

Constructs a unknown-format demo card from a file at path.

copy_assets_and_configs(src_page_dir, dst_build_dir=pwd())

copy only assets, configs and templates from src_page_dir to dst_build_dir. The folder structure is preserved under dst_build_dir/$(basename(src_page_dir))

order in config files are modified accordingly.

democard(path::String)::T

Constructs a concrete AbstractDemoCard instance.

The return type T is determined by the extension of the path to your demofile. Currently supported types are:

• MarkdownDemoCard for markdown files
• JuliaDemoCard for julia files
• PlutoDemoCard for pluto files
• UnmatchedCard for unmatched files

generate_or_copy_pagedir(src_path, build_dir)

copy the page folder structure from src_path to build_dir/$(basename(src_path). If src_path does not live in a standard demo page folder structure, generate a preview version.

return case-insensitive alphabetic order

infer_pagedir(card_path; rootdir="")

Given a demo card path, infer the outmost dir path that makes it a valid demo page. If it fails to find such dir path, return nothing.

The inference is done recursively, rootdir sets a stop condition for the inference process.

testdir/
└── examples
    └── sections
        └── demo1.md

input_bool(prompt)::Bool

Print prompt message and trigger user input for confirmation.

makedemos(source::String;
          root = "<current-directory>",
          src = "src",
          build = "build",
          branch = "gh-pages",
          edit_branch = "master",
          credit = true,
          throw_error = false) -> page_path, postprocess_cb

Make a demo page for source and return the path to the generated index file.

Processing pipeline:

1. analyze the folder structure source and loading all available configs.
2. copy assets
3. preprocess demo files and save it
4. save/copy cover images
5. generate postprocess callback function, which includes url-redirection.

Inputs

• source: dir path to the root page of your demos; relative to docs.

Outputs

• page_path: path to demo page's index. You can directly pass it to makedocs.
• postprocess_cb: callback function for postprocess. You can call postprocess_cb() after makedocs.
• theme_assets: the stylesheet assets that you may need to pass to Documenter.HTML. When the demo page has no theme, it will return nothing.

Keywords

• root::String: should be equal to Documenter's setting. Typically it is "docs" if this function is called in docs/make.jl file.
• src::String: should be equal to Documenter's setting. By default it's "src".
• build::String: should be equal to Documenter's setting. By default it's "build".
• edit_branch::String: should be equal to Documenter's setting. By default it's "master".
• branch::String: should be equal to Documenter's setting. By default it's "gh-pages".
• credit::Bool: true to show a "This page is generated by ..." info. By default it's true.
• throw_error::Bool: true to throw an error when the julia demo build fails; otherwise it will continue the build with warnings.
• filter_function::Function: the function is passed each potential DemoCard, and the card is excluded if the function returns false. By default, all potential cards are included.

Examples

The following is the simplest example for you to start with:

# 1. preprocess and generate demo files to docs/src
examples, postprocess_cb, demo_assets = makedemos("examples")

assets = []
isnothing(demo_assets) || (push!(assets, demo_assets))

# 2. do the standard Documenter pipeline
makedocs(format = Documenter.HTML(assets = assets),
         pages = [
             "Home" => "index.md",
             examples
         ])

# 3. postprocess after makedocs
postprocess_cb()

By default, it won't generate the index page for your demos. To enable it and configure how index page is generated, you need to create "examples/config.json", whose contents should looks like the following:

{
    "theme": "grid",
    "order": [
        "basic",
        "advanced"
    ]
}

For more details of how config.json is configured, please check DemoCards.DemoPage.

meta_edit_url(path)

helper to add in corrected edit link for markdown files which will be processed by Documenter.jl later

parse([T::Val], card::AbstractDemoCard)
parse(T::Val, contents)
parse(T::Val, path)

Parse the content of card and return the configuration.

Currently supported items are: title, id, cover, description.

preview_demos(demo_path; kwargs...)

Generate a docs preview for a single demo card.

Return values

• index_file: absolute path to the index file of the demo page. You can open this in your browser and see the generated demos.

Arguments

• demo_path: path to your demo file or folder. It can be path to the demo file, the folder of multiple scripts. If standard demo page folder structure is detected, use it, and otherwise will create a preview version of it.

Parameters

• theme: the card theme you want to use in the preview. By default, it infers from your page config file. To not generate index page, you could pass nothing to it. See also cardtheme for theme choices.
• assets = String[]: this is passed to Documenter.HTML
• edit_branch = "master": same to that in makedemos
• credit = true: same to that in makedemos
• throw_error = false: same to that in makedemos
• require_html = true: if it needs to trigger the Documenter workflow and generate HTML preview. If set to false, the return value is then the path to the generated index.md file. This is an experimental keyword and should not be considered stable.
• clean = true: whether you need to first clean up the existing sandbox building dir.

save_cover(path::String, card::AbstractDemoCard)

process the cover image and save it.

save_democards(root::String, page::DemoPage; credit, nbviewer_root_url)

recursively process and save source demo file

save_democards(card_dir::String, card::JuliaDemoCard;
               project_dir,
               src,
               credit,
               nbviewer_root_url)

process the original julia file and save it.

The processing pipeline is:

1. preprocess and copy source file
2. generate ipynb file
3. generate markdown file
4. insert header and footer to generated markdown file

save_democards(card_dir::String, card::MarkdownDemoCard)

process the original markdown file and save it.

The processing pipeline is:

1. strip the front matter
2. insert a level-1 title and id

split_frontmatter(contents) -> frontmatter, body

splits the YAML frontmatter out from markdown and julia source code. Leading # will be stripped for julia codes.

contents can be String or vector of String. Outputs have the same type of contents.

walkpage([f=identity], page; flatten=true, max_depth=Inf)

Walk through the page structure and apply function f to each of the item.

By default, the page structure is not preserved in the result. To preserve that, you could pass flatten=false to the function.

Examples

This is particulaly useful to generate information for the page structure. For example:

julia> page = DemoPage("docs/quickstart/");

julia> walkpage(page; flatten=true) do item
    basename(item.path)
end

"Quick Start" => [
    "simple_markdown_demo.md",
    "configure_card.md",
    "configure_sec_and_page.md",
    "hide_your_card_from_index.md",
    "hidden_card.jl",
    "1.julia_demo.jl",
    "2.cover_on_the_fly.jl"
]

If flatten=false, then it gives you something like this:

"Quick Start" => [
    "Usage example" => [
        "Basics" => [
            "simple_markdown_demo.md",
            "configure_card.md",
            "configure_sec_and_page.md",
            "hide_your_card_from_index.md",
            "hidden_card.jl"
        ],
        "Julia demos" => [
            "1.julia_demo.jl",
            "2.cover_on_the_fly.jl"
        ]
    ]
]

cardtheme(theme = "grid";
          root = "<current-directory>",
          src = "src",
          destination = "democards") -> templates, stylesheet_path

For given theme, return the templates and path to stylesheet.

root and destination should have the same value to that passed to makedemos.

Available themes are:

• "bulmagrid"
• "bokehlist"
• "grid"
• "list"
• "nocoverlist"
• "transitiongrid"