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 initinit命令将询问您一些问题，并为您设置默认项目。默认响应用方括号表示，例如[false]。
要构建包含的默认项目，请运行
runestone build注意：如果在构建项目时遇到与six库的版本冲突，pip install --ignore-installed six命令可能很有用。
现在您将有一个包含index.html文件的构建文件夹，以及一些默认内容。构建文件夹的内容适合在任何可以提供静态网页内容的地方托管！对于一个小型班级，您甚至可以使用提供的Python网络服务器提供内容。
$ runestone serve现在，从您的浏览器中打开https://:8000/index.html，您应该看到如下示例页面的目录
如果您编辑_sources/index.html或_sources/overview.rst，然后重新构建并再次提供服务，您将看到您的更改。最好的文档可能是overview.rst文件本身，因为它展示了如何使用所有常用组件，并展示了它们的大部分选项。
Windows用户 我已测试了在Windows 8.1上安装以及init、build和serve。最大的问题是可能需要设置PATH环境变量，以便您可以从shell中简单地输入命令。请注意，我并不是Windows的常规用户，我只是偶尔在我的VMWare安装上测试一些事情。如果您是Windows上Python的新用户，我建议您查看使用Windows与Python的相关链接
开发和破解
因此，您想帮助开发Runestone组件。太好了，我们欢迎所有我们能得到的帮助。无论您的经验水平如何，都有很多事情要做。有一些先决条件。
您需要一个Python版本，我目前正在使用3.9或更高版本进行开发，但也在3.8及以后进行测试。
由于组件中有很多JavaScript代码，您还需要nodejs和npm。
要设置好一切，请执行以下操作
从本仓库创建一个分支，并将仓库通过 git clone 命令克隆到您的开发机器上。
安装 Poetry
从 RunestoneComponents 的顶级目录运行 npm install，这将安装用于 JavaScript 开发的打包工具。使用 npm run 命令可以列出命令列表。关键命令是 npm run build，这将把所有组件的 JavaScript 和 CSS 文件合并成一个 runestone.js 文件。如果您正在进行一些深度开发并且希望避免构建书籍，可以将您的 HTML 放在 public/index.html 中，并使用 npm run start 命令。这将在每次保存更改时自动重建 runestone.js 并刷新网页。
当您有一些更改要分享时，请发起一个 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},
}
下载文件
下载适合您平台的文件。如果您不确定选择哪个，请了解更多关于安装包的信息。
源分布
构建分布
runestone-7.4.2.tar.gz的哈希值
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | 51d7c7eef3a1c1107e723bceab7e0974748a99f23eacfc0800b347e1a0e33a38 |
|
| MD5 | 28e30c523f8624d273b798c337c99f1c |
|
| BLAKE2b-256 | f5dc6621db77f440bb6be4563a88bd968bf18c7e5391ad4b07ba1283b8aa3891 |