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,您应该看到如下示例页面的目录
如果您编辑_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 |