nbprint 0.1.10

用于使用 nbconvert 构建打印媒体的框架。

安装

使用 pip 安装

pip install nbprint

使用 conda 安装

conda install nbprint -c conda-forge

背景

Jupyter笔记本广泛用于通过 nbconvert 创建报告。大多数努力都集中在从笔记本构建网页报告/网站，包括 Voilà 和 Jupyter Book。

尽管早期笔记本转换工作的主要目标是这个，但在最近几年，对打印媒体的关注较少 - 包括报告、学术论文、报纸等PDF。有许多用于学术论文的 nbconvert 模板，以及像 ipypublish 这样的项目。这些努力大多集中在 $\LaTeX$，事实上，nbprint 本身最初也是一个方便的框架，用于在html和pdf输出之间格式化图表和表格。

然而，随着最近对 nbconvert 的更新，它现在支持 webpdf（在无头网络浏览器中打印为 PDF），以及 @media print CSS 指令的进步，该指令由来自 pagedjs 的可爱的人们引领，现在在网络上构建准备发布的打印媒体要容易得多。

这是 nbprint 的目标。使用 pagedjs，nbprint 提供了针对打印媒体的 Web 报告的模板和实用工具。除此之外，它还通过 pydantic 提供了参数化和配置文档的基础设施，这使得设计和生成报告变得轻而易举，甚至无需了解 Python。

快速入门

nbprint 可以仅通过笔记本元数据来使用，但它还提供了一个基于 yaml 的框架来配置（通过 pydantic 和 omegaconf）。这在生成参数化报告时尤其方便，例如在配置模型评估报告的大量超参数时。这种配置还可以使报告的设计和内容更容易迭代。

配置

让我们以一个简单的占位符报告为例。

---
debug: false
outputs:
  type: nbprint:NBConvertOutputs
  path_root: ./examples/output
  target: "html"

content:
  - type: nbprint:ContentMarkdown
    content: |
      # A Generic Report
      ## A Subtitle
    css: ":scope { text-align: center; }"

  - type: nbprint:ContentPageBreak

  - type: nbprint:ContentTableOfContents

  - type: nbprint:ContentPageBreak

  - type: nbprint:ContentMarkdown
    content: |
      # Section One
      Lorem ipsum dolor sit amet.
      ## Subsection One
      Consectetur adipiscing elit, sed do eiusmod tempor incididunt.
      ## Subsection Two
      Ut labore et dolore magna aliqua.

  - type: nbprint:ContentPageBreak

  - type: nbprint:ContentFlexRowLayout
    sizes: [1, 1]
    content:
      - type: nbprint:ContentFlexColumnLayout
        content:
          - type: nbprint:ContentMarkdown
            content: |
              # Section Two
              Lorem ipsum dolor sit amet.
              ## Subsection One
              Consectetur adipiscing elit, sed do eiusmod tempor incididunt.

      - type: nbprint:ContentFlexColumnLayout
        content:
          - type: nbprint:ContentMarkdown
            content: |
              # Section Three
              Ut labore et dolore magna aliqua.
              ## Subsection One
              Ut enim ad minim veniam, quis nostrud.

让我们一步一步地分解。

首先，我们配置 debug: false。这告诉 nbprint 运行 pagedjs 打印预览。我们还设置输出以运行 nbconvert 并配置输出文件夹的位置。

接下来我们填写一些内容。这里我们使用了一些组件

• ContentMarkdown 生成 Markdown 单元
• ContentPageBreak 在我们的 PDF 中分割到新的一页
• ContentTableOfContents 创建目录。请注意，这将同时适用于 html 预览和 pdf 形式！
• ContentFlexRowLayout 和 ContentFlexColumnLayout 创建文档的布局结构。

运行

我们现在可以通过运行 CLI 生成报告

nbprint examples/basic.yaml basic

这将在我们指定的文件夹 examples/output 中创建一个 Notebook 输出，以及一个 html 资产（因为我们已在 yaml 文件中指定）。两者都将有日期作为后缀，这也可以在我们的 yaml 中进行配置。我们看到生成的报告笔记本，我们可以打开它并进行进一步的实验，或调查报告本身。

我们还看到 html 文档本身，它将通过 pagedjs 打印预览来渲染。

您可以在这里找到这份文档的 PDF 版本。

开发

警告：此项目正在积极开发中，因此所有 API 都可能发生变化！

相关项目

• nbconvert：将笔记本转换为其他格式
• pagedjs：Paged.js 是一个免费的开源库，可以将任何 HTML 内容分页以生成美观的打印就绪 PDF
• Voilà：Voilà 将 Jupyter 笔记本转换为独立的网络应用程序
• Jupyter Book：从计算内容构建美观的、出版物质量的书籍和文档
• ipypublish：创建和编辑准备发布的科学报告和演示文稿的工作流程，从一个或多个 Jupyter 笔记本开始，无需离开浏览器！

此外，此项目严重依赖于

• pydantic：Pydantic 是 Python 中最广泛使用的数据验证库。
• omegaconf：OmegaConf 是一个分层配置系统，支持从多个来源合并配置
• typer：Typer 是一个基于 Python 类型提示构建 CLI 应用程序的库

许可证

本软件根据 Apache 2.0 许可证授权。有关详细信息，请参阅 LICENSE 文件。