naucse_render

将YAML/Markdown/Jupyter格式的课程材料转换为 naucse.python.cz JSON API的辅助工具。

入口点

获取可用课程的列表

naucse_render.get_course_slugs(*, path='.')

获取一般课程信息

naucse_render.get_course(course_slug, *, path='.', version=None)

获取有关课程的信息

naucse_render.get_lessons(lesson_slugs, vars=None, path='.')

将指定课程编译为目录中的JSON和HTML文件

def compile(slug=None, *, path='.', destination, edit_info=None)

path指定了本地文件系统中的仓库根路径（即courses、runs和lessons的父目录）。

安装和CLI使用

从PyPI安装最新发布的版本。在有活动的virtualenv的情况下，执行

(venv)$ pip install naucse_render

对于开发，您可以使用dev依赖项以可编辑模式安装

(venv)$ pip install -e.[dev]

您可以从命令行运行naucse_render。要将课程“编译”为JSON元数据和静态文件的目录

(venv)$ python -m naucse_render compile _built/

输出课程或单个课程（s）的元数据

(venv)$ python -m naucse_render get-course

(venv)$ python -m naucse_render get-lessons beginners/install beginners/venv-setup

默认情况下，数据从当前工作目录检索。使用--path选项将naucse_render指向其他位置。

您可以使用--help获取更多信息。

测试

要运行测试，请使用开发依赖项安装此包

(venv)$ pip install -e.[dev]

然后使用pytest运行测试

(venv)$ python -m pytest

许可证

代码根据MIT许可证的条款进行许可，有关完整文本，请参阅LICENSE.MIT文件。通过向此存储库贡献代码，您同意将其许可在同一许可证下。

变更日志

naucse_render 2.0

• 更新到mistune 3.x & nbconvert 7.x。这改变了Markdown的解析和格式化、语法高亮和笔记本。在大多数情况下，这些差异应该是表面的。

• 在Python 3.8-3.12上进行了测试

naucse_render 1.10

• naucse_render compile 现在会检查课程中缺失的课程链接和不存在 id，如果发现则失败。

• 修复了标题后的链接

• API版本 0.4

  • 每个课程页面现在都有一个 links 条目，其中包含页面上找到的所有链接。
  • 每个课程页面现在都有一个 ids 条目，其中包含页面上找到的所有 id 属性。

naucse_render 1.9

• naucse_render 现在支持 Jinja2 的当前版本。

naucse_render 1.8

• naucse_render compile 现在支持 --all 开关，它将所有可用的课程编译到目标目录下的目录中。如果没有指定 --slug 并且没有找到默认课程，这将是默认操作。此更改应允许使用针对所有具有课程定义的存储库的通用 CI 配置。
• 现在自动为所有标题添加锚点，使得可以链接到单个部分。（感谢 Jakub Beránek）

naucse_render 1.7

• 添加了 naucse.get_course_slugs() 函数和 CLI 子命令 naucse_render ls，它们返回 naucse_render 可以从给定目录中加载的课程列表。
• 课程现在可以使用类似于 courses/<course-slug>.yml 的“扁平”文件来指定，而不是在目录中嵌套的 info.yml 文件。

naucse_render 1.6

• 课程现在可以指定 extra_lessons，这是一个列表，其中包含即使在会话材料中未出现，编译也会包含在内的课程。这比依赖于课程内容中的链接（每次需要此信息时都需要解析，会使速度变慢）更明确。

naucse_render 1.5

• 新的子命令 compile 创建一个包含课程数据和辅助文件的目录。

• API版本 0.3

  • 课程现在可以有关“编辑信息”的信息，指定课程源可以编辑的位置。（这仅在编译课程时设置；在其他情况下，调用者应知道代码的位置。）

• 现在 slug 是可选的；如果没有给出（或为 None），则从 course.yml 中加载数据（在给定的 path 中，默认为当前目录），而不是从 runs/ 或 courses/ 中的文件。

naucse_render 1.4

与 nbconvert 6.0 兼容。

naucse_render 1.3

• 忽略没有数据的课程目录（https://github.com/pyvec/naucse_render/issues/15）
• API版本 0.2
• 子页面现在有副标题
  • 非 index 子页面现在可以选择性地具有一个 subtitle。例如，一个名为“安装”的课程可能有一个 OS 特定的子页面，副标题为“Linux”。
  • 现在，非 index 子页面的 title 可能缺失在输入中。在这种情况下，必须存在 subtitle，并且 title 将生成为 "{课程标题} – {页面副标题}"。
• 传递时区信息
• 从 YAML 读取的映射必须具有唯一的键。
• 子页面现在可以使用相对 URL 链接： ./page，就像其他课程可以用 ../lesson 或 ../../category/lesson 链接一样。（对其他课程的子页面进行“简短”链接，例如 ../lesson/page，仍然不起作用。）

naucse_render 1.2

• API版本 0.1
• 会话现在生成序列“编号”。
  • 序列是字符串（或 None）。通常它们是数字的（如 '1'），在源 YAML 中可以指定为 int。但是，例如，附录可以使用罗马数字： i、ii、iii。
  • 如果源 YAML 中未显式给出序列，则自动生成为前一个序列加 1（或从 1 开始）。指定为 str（或 None）的序列会阻止此自动生成。
  • 对于只有一个会话的课程，不会自动生成序列。

naucse_render 1.1

• 使能够使用 YAML 文件中的数据来填充课程内容
• 使Windows上的输出与“类Unix”系统上的输出相同

naucse_render 1.0

• 源文件始终报告为相对路径
• 当YAML文件更改时，将重新加载它们
• 添加了集成测试

naucse_render 0.x

0.x应该能够成功渲染2019年之前在 naucse.python.cz 上托管的课程。

源文件的格式是自然发展的，因此这里没有尝试对其进行文档化。