3 Embeded objects

Pheasant can embed codes from a file system or Python module.

3.1 File system

Extenal resources are read from file system by Pheasant syntax: {%=object%}. For example,

{%=/mkdocs.yml%}

writes the content of the real mkdocs.yml of this document:

site_name: Pheasant
site_url: https://pheasant.daizutabi.net/
site_description: Project documentation with MkDocs.
site_author: daizutabi

repo_url: https://github.com/daizutabi/pheasant/
edit_uri: ""

theme:
    name: readthedocs
    hljs_languages:
      - yaml
    custom_dir: custom_theme/

extra_css:
  - css/extra.css

extra_javascript:
  - js/extra.js

plugins:
  - pheasant:

nav:
  - Home: index.md
  - User Guide:
    - Images: user-guide/images.md
    - Embed: user-guide/embed.md
    - SymPy: user-guide/sympy.md
    - Script: user-guide/script.py
    - Kernel: user-guide/kernel.md
  - About:
    - Release Notes: about/release-notes.md
    - License: about/license.md

markdown_extensions:
  - admonition
  - pymdownx.arithmatex

The root directory is the directory where mkdocs.yml exists.

If the file is too long to display the whole content, you can specify the lines as the same way of Python's slice notation.

{%=/mkdocs.yml[3:8]%}
site_author: daizutabi

repo_url: https://github.com/daizutabi/pheasant/
edit_uri: ""

Imported file can be numbered like figures and tables. Use this inline notation:

#File {%=/mkdocs.yml[:8]%}

File 1

site_name: Pheasant
site_url: https://pheasant.daizutabi.net/
site_description: Project documentation with MkDocs.
site_author: daizutabi

repo_url: https://github.com/daizutabi/pheasant/
edit_uri: ""

3.2 Python module source

Python module sources that the current Jupyter kernel can find are also inspected. Now Pheasant imported its own package pheasant, so you can read the source from this document by Pheasant syntax: {%?object%}.

You can write to inspect the whole module content:

import pheasant

[1] 2019-04-24 22:14:38 (5.00ms) (run) python3 (1.21s)

{%?pheasant%}
__version__ = "2.2.19"

A part of the module can be specified as usual.

from pheasant.renderers.jupyter.jupyter import Jupyter

[2] 2019-04-24 22:14:38 (25.0ms) python3 (1.24s)

{%?Jupyter[:21]%}
class Jupyter(Renderer):
    option: str = field(default="", init=False)
    count: int = field(default=0, init=False)
    cache: List[Cell] = field(default_factory=list, init=False)
    extra_html: str = field(default="", init=False)
    progress_bar: ProgressBar = field(default_factory=ProgressBar, init=False)
    enabled: bool = field(default=True, init=False)
    safe: bool = field(default=False, init=False)  # If True, code must match cache.

    FENCED_CODE_PATTERN = (
        r"^(?P<mark>`{3,})(?P<language>\w*) ?(?P<option>.*?)\n"
        r"(?P<code>.*?)\n(?P=mark)\n"
    )
    INLINE_CODE_PATTERN = r"\{\{(?P<code>.+?)\}\}"
    RE_INLINE_CODE_PATTERN = re.compile(INLINE_CODE_PATTERN)

    def init(self):
        self.register(Jupyter.FENCED_CODE_PATTERN, self.render_fenced_code)
        self.register(Jupyter.INLINE_CODE_PATTERN, self.render_inline_code)
        self.set_template(["fenced_code", "inline_code"])

With this functionality, you can guarantee the reproducible relation between your source code and results easily.

3.3 Include other file as Markdown source.

Assume that there is a directory named link under the same directory of this file and there are some files under the link directory. You can include the content of a file like below:

{% link/included.md %}

[The content of included.md]

You can also include a pure Python source code.

{% link/included.py %}

Script can be included.

def func(x, y):
    return x + y

[3] 2019-04-24 22:14:38 (6.03ms) python3 (1.27s)

If the included file contains header statements, the document structure may be broken. For example, a file to be included contains:

File 2 link/section.md

# Title

## Section

Text.

If you include the file, a new <h1> section starts that you don't want to. To maintain the document structure, you can shift the header level like below. Note that we are under a <h2> section now.

{% link/section.md>2 %}

In this case, "# Title" becomes "### Title" by ">2".