Edit on GitHub

Package References

DemoCards.makedemos — Method
makedemos(source::String, templates::Dict;
          root = "<current-directory>",
          destination = "democards",
          src = "src",
          build = "build",
          branch = "gh-pages",
          edit_branch = "master",
          credit = true) -> 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.
Note

By default, the source demo files are read, processed and save to docs/src/democards, so if you put all source demo files in docs/src, there will be a duplication of files and assets. Thus, it's recommended to not put your original page folder in docs/src, and it's prefered to git ignore docs/src/democards

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.

Keywords

  • root::String: should be equal to Documenter's setting. By default it's "docs".
  • destination::String: The folder name in generated documentation. By default it's "democards".
  • 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::String: true to show a "This page is generated by ..." info. By default it's true.

Examples

The following is a minimal example for you to start

# 1. generate templates and stylesheets with predefined themes
templates, theme = cardtheme()

# 2. preprocess and generate demo files to docs/src/democards
examples, postprocess_cb = makedemos("examples", templates)

# 3. pass stylesheet to HTML assets
format = Documenter.HTML(edit_branch = "master",
                         assets = [theme])

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

# 5. postprocessing
postprocess_cb()
source
DemoCards.DemoPage — Type
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}}}.
  • title: specify the title of this demo page. By default, it's the folder name of root. Will be override by template.

The following is an example of config.json:

{
    "template": "template.md",
    "order": [
        "basic",
        "advanced"
    ]
}

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
Note

A DemoPage doesn't manage demo files directly, so here you'll need a DemoSection basic to manage them.

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
Warning

A section should only hold either subsections or demo files. A folder that has both subfolders and demo files (e.g., *.md) is invalid.

See also: MarkdownDemoCard, DemoSection

source
DemoCards.DemoSection — Type
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.

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"
    ]
}

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
Warning

A section should only hold either subsections or demo files. A folder that has both subfolders and demo files (e.g., *.md) is invalid.

See also: MarkdownDemoCard, DemoPage

source
DemoCards.JuliaDemoCard — Type
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
  • description: multi-line description of the demo card

Configuration

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

  • cover: 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).

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

# ---
# title: passing extra information
# cover: cover.png
# id: non_ambiguious_id
# description: this demo shows how you can pass extra demo information to DemoCards package.
# ---

See also: MarkdownDemoCard, DemoSection, DemoPage

source
DemoCards.MarkdownDemoCard — Type
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
  • description: multi-line description of the demo card

Configuration

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

  • cover: 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).

An example of the front matter:

---
title: passing extra information
cover: cover.png
id: non_ambiguious_id
description: this demo shows how you can pass extra demo information to DemoCards package.
---

See also: JuliaDemoCard, DemoSection, DemoPage

source
DemoCards.democard — Method
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:

source
DemoCards.parse — Method
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.

Note

Users of this function need to use haskey to check if keys are existed. They also need to validate the values.

source
DemoCards.redirect_link — Method
redirect_link(src_file, source, root, destination, src, build, edit_branch)

Redirect the "Edit On GitHub" link of generated demo files to its original url, without this a 404 error is expected.

source
DemoCards.save_democards — Method
save_democards(root::String, page::DemoPage; credit, nbviewer_root_url)

recursively process and save source demo file

source
DemoCards.save_democards — Method
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
source
DemoCards.save_democards — Method
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
source
DemoCards.split_frontmatter — Method
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.

source