跳转到主要内容

Sphinx扩展,用于编写交互式文档。

项目描述

使用Sphinx和reStructuredText发布教育材料的Runestone组件打包。查看 概述 以查看所有扩展的实际操作。

Runestone版本7

重要 2023年5月将RunestoneComponents仓库移动到新的单仓项目。

要构建包含交互式组件javascript的runestone发布版本,请使用此文件夹中的build.py脚本。

python build.py

要构建发布版本并将其发布到PyPI,请使用 --publish 选项

python build.py --publish

发布选项假定您有在PyPI上发布的凭据,以及runestone负载均衡器的凭据。

文档

从2022年夏季起,使用Runestone RST标记语言编写新书已被弃用。强烈建议您使用PreTeXt标记语言来编写新书。

  • 请参阅《示例书籍 <https://pretextbook.org/examples/sample-book/annotated/sample-book.html>》,特别是第3章,标题为“交互练习”的部分。您在示例书籍中看到的activecode、CodeLens以及所有其他交互式组件都是由本存储库中的组件驱动的。这个存储库将是这些交互组件的家园。

  • 请参阅《PreTeXt指南》。它包含了关于使用PreTeXt编写的全面文档。

  • 作为作者,您将希望使用PreTeXt CLI来编写书籍。有经验的Runestone作者会发现PreTeXt CLI非常熟悉,但组织得更好,配置文件更少。请参阅《PreTeXt-CLI <https://pretextbook.org/doc/guide/html/guide-toc.html>

快速开始

  • pip install pretext

  • 为您的书籍项目创建一个文件夹,然后运行

  • pretext new来创建一个新的书籍。

旧版文档

在过渡到PreTeXt期间,我会保留这部分内容一段时间。

要开始使用Runestone restructuredText作为标记语言

  • pip install runestone

要启动一个项目,创建一个新文件夹,然后在那个新文件夹中运行以下命令(由pip安装):runestone init 例如

mkdir myproject
cd myproject
runestone init

init命令将询问您一些问题,并为您设置默认项目。默认响应用方括号表示,例如[false]

要构建包含的默认项目,请运行

runestone build

注意:如果在构建项目时遇到与six库的版本冲突,pip install --ignore-installed six命令可能很有用。

现在您将有一个包含index.html文件的构建文件夹,以及一些默认内容。构建文件夹的内容适合在任何可以提供静态网页内容的地方托管!对于一个小型班级,您甚至可以使用提供的Python网络服务器提供内容。

$ runestone serve

现在,从您的浏览器中打开https://:8000/index.html,您应该看到如下示例页面的目录

images/runeCompo-index.png

如果您编辑_sources/index.html_sources/overview.rst,然后重新构建并再次提供服务,您将看到您的更改。最好的文档可能是overview.rst文件本身,因为它展示了如何使用所有常用组件,并展示了它们的大部分选项。

Windows用户 我已测试了在Windows 8.1上安装以及init、build和serve。最大的问题是可能需要设置PATH环境变量,以便您可以从shell中简单地输入命令。请注意,我并不是Windows的常规用户,我只是偶尔在我的VMWare安装上测试一些事情。如果您是Windows上Python的新用户,我建议您查看使用Windows与Python的相关链接

开发和破解

因此,您想帮助开发Runestone组件。太好了,我们欢迎所有我们能得到的帮助。无论您的经验水平如何,都有很多事情要做。有一些先决条件。

  1. 您需要一个Python版本,我目前正在使用3.9或更高版本进行开发,但也在3.8及以后进行测试。

  2. 由于组件中有很多JavaScript代码,您还需要nodejs和npm。

要设置好一切,请执行以下操作

  1. 从本仓库创建一个分支,并将仓库通过 git clone 命令克隆到您的开发机器上。

  2. 安装 Poetry

  3. 从 RunestoneComponents 的顶级目录运行 npm install,这将安装用于 JavaScript 开发的打包工具。使用 npm run 命令可以列出命令列表。关键命令是 npm run build,这将把所有组件的 JavaScript 和 CSS 文件合并成一个 runestone.js 文件。如果您正在进行一些深度开发并且希望避免构建书籍,可以将您的 HTML 放在 public/index.html 中,并使用 npm run start 命令。这将在每次保存更改时自动重建 runestone.js 并刷新网页。

  4. 当您有一些更改要分享时,请发起一个 Pull Request。

(有关该项目如何工作的更完整文档,请参阅 RunestoneServer 仓库和 http://runestoneinteractive.org。)

代码风格

我们使用 black 自动格式化 Python 代码。您可以将编辑器设置为在保存时自动运行 black,或者您可以手动运行它。

我们使用 prettier 自动格式化 JavaScript。

在您的代码上运行 jshint,我们为此项目配置了一些选项。

编写测试

向 Runestone Components 仓库添加测试套件是做出贡献的好方法。

我们的目标是针对每个指令编写单元测试,这些测试依赖于 Selenium(一个帮助模拟网页浏览器交互的库),以检查驱动指令的 JavaScript 是否工作正常。

为了开始编写测试或添加更多测试,您需要以下内容

  • 下载最新的 ChromeDriver,这是一个模拟 Google Chrome 的驱动程序。

  • 在 Linux 上,您需要安装 Xvfb apt-get install xvfb

  • 您还需要完成上述安装。

  • 我们已经将依赖关系管理转换为使用 poetry。要在开发模式下运行 runestone,请使用 poetry run runestone … 或者运行 poetry shell 以启动一个具有激活虚拟环境的 shell。

要运行测试

  • 请确保包含 ChromeDriver 可执行文件的目录在您的 PATH 环境变量中。例如,在命令行中输入 PATH=$PATH:path/to/chromedriver(或编辑您的 .bash_profile)。

  • 查看现有测试,例如测试 Question 指令的 test_question.py 文件,您可以在路径 /runestone/question/test/test_question.py 中找到它,以获取示例。

  • 每个指令的独立测试集都需要一个小型书籍。您会在每个现有测试的 _sources 文件夹中看到一个包含 index.rst 文件的文件夹。该文件包含一个标题,这是由 .rst 所需的,以及您想要测试的任何指令示例。

  • 最后,要运行测试,确保您已访问指令文件夹,请在命令提示符下输入以下内容

    • poetry run pytest

从主目录运行 pytest 将运行所有测试。要运行单个测试,您可以导航到测试所在的目录,或者运行 poetry run pytest -k XXX,其中 XXX 是匹配测试函数名称的一部分的子串。

然后您应该会看到一些测试输出,显示通过(ok)、失败或错误。

如果输出中有关PhantomJS/驱动程序的错误,您可能存在PATH或驱动程序安装问题。

要编写新测试

  • 在指令文件夹内创建一个test目录

  • 在该目录内创建一个Python文件以保存测试套件,例如test_directivename.py

  • 在该文件夹内运行runestone init并回答以下提示

  • index.rst文件内(由runestone init创建)编写适当的指令示例

  • 根据需要编辑您创建的Python文件(请参阅Python unittest模块的文档在Python文档中。)

高级用户注意事项

如果您已经有一个现有的Sphinx项目,并且希望将Runestone组件集成到项目中,您只需对现有的conf.py文件进行一些简单的编辑。

  • 首先添加以下导入行from runestone import runestone_static_dirs, runestone_extensions

  • 然后修改您的扩展。您可能已经启用了不同的扩展集,但没关系,只需这样做:extensions = ['sphinx.ext.mathjax'] + runestone_extensions()

  • 然后修改您的html_static_path:html_static_path = ['_static'] + runestone_static_dirs() 再次,您可能在自己的初始列表中有自己的静态路径。

请参阅https://github.com/bnmnetp/runestone/wiki/DevelopmentRoadmap以了解这一切如何结合在一起。

研究人员

如果您在研究中使用Runestone或撰写有关它的文章,请引用https://runestone.academy并引用此论文

@inproceedings{Miller:2012:BPE:2325296.2325335,
 author = {Miller, Bradley N. and Ranum, David L.},
 title = {Beyond PDF and ePub: Toward an Interactive Textbook},
 booktitle = {Proceedings of the 17th ACM Annual Conference on Innovation and Technology in Computer Science Education},
 series = {ITiCSE '12},
 year = {2012},
 isbn = {978-1-4503-1246-2},
 location = {Haifa, Israel},
 pages = {150--155},
 numpages = {6},
 url = {http://doi.acm.org/10.1145/2325296.2325335},
 doi = {10.1145/2325296.2325335},
 acmid = {2325335},
 publisher = {ACM},
 address = {New York, NY, USA},
 keywords = {cs1, ebook, sphinx},
}

项目详情


发布历史 发布通知 | RSS源

下载文件

下载适合您平台的文件。如果您不确定选择哪个,请了解更多关于安装包的信息。

源分布

runestone-7.4.2.tar.gz (29.2 MB 查看哈希值)

上传

构建分布

runestone-7.4.2-py3-none-any.whl (29.3 MB 查看哈希值)

上传 Python 3

支持者