sphinx-touchbook 0.1.0__tar.gz

sphinx_touchbook-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Byte-code
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Python packaging
+dist/
+
+# Sphinx documentation
+docs/_build/
+_build/
+build/
+
+# Python Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# JavaScript dependencies
+node_modules/

sphinx_touchbook-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+Unless otherwise indicated, all code in the Sphinx-Touchbook project is
+licenced under the two clause BSD licence below.
+
+Copyright (c) 2026, Dave Parillo,
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

sphinx_touchbook-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: sphinx-touchbook
+Version: 0.1.0
+Summary: Sphinx directives and Web Components for interactive textbook content.
+Project-URL: Homepage, https://github.com/DaveParillo/sphinx-touchbook
+Project-URL: Issues, https://github.com/DaveParillo/sphinx-touchbook/issues
+Author-email: Dave Parillo <dparillo@sdccd.edu>
+License: Unless otherwise indicated, all code in the Sphinx-Touchbook project is
+        licenced under the two clause BSD licence below.
+        
+        Copyright (c) 2026, Dave Parillo,
+        All rights reserved.
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are
+        met:
+        
+        * Redistributions of source code must retain the above copyright
+          notice, this list of conditions and the following disclaimer.
+        
+        * Redistributions in binary form must reproduce the above copyright
+          notice, this list of conditions and the following disclaimer in the
+          documentation and/or other materials provided with the distribution.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+        "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+        LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+        A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+        HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+        SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+        LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+        DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+        THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+        (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Sphinx :: Extension
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Documentation :: Sphinx
+Classifier: Topic :: Education
+Requires-Python: >=3.10
+Requires-Dist: sphinx>=7
+Provides-Extra: docs
+Requires-Dist: sphinx-nefertiti; extra == 'docs'
+Requires-Dist: sphinx>=7; extra == 'docs'
+Provides-Extra: publish
+Requires-Dist: build; extra == 'publish'
+Requires-Dist: hatchling; extra == 'publish'
+Requires-Dist: twine; extra == 'publish'
+Provides-Extra: test
+Requires-Dist: beautifulsoup4; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Description-Content-Type: text/markdown
+
+# sphinx-touchbook
+[![Tests](https://img.shields.io/github/actions/workflow/status/daveparillo/sphinx-touchbook/publish-authorguide.yml?branch=main&label=tests)](https://github.com/daveparillo/sphinx-touchbook/actions/workflows/publish-authorguide.yml)
+[![Author Guide](https://img.shields.io/github/actions/workflow/status/daveparillo/sphinx-touchbook/publish-authorguide.yml?branch=main&label=docs)](https://github.com/daveparillo/sphinx-touchbook/actions/workflows/publish-authorguide.yml)
+[![License](https://img.shields.io/github/license/daveparillo/sphinx-touchbook)](LICENSE)
+
+`sphinx-touchbook` is a Sphinx extension project for authors who want
+interactive textbook pages without giving up ordinary Sphinx documents.
+Authors write semantic reStructuredText directives, Sphinx parses them into
+docutils nodes, Python generators render builder-specific output, and
+JavaScript components progressively enhance the generated HTML.
+
+This project is inspired by
+[Runestone Interactive](https://github.com/RunestoneInteractive),
+which pioneered interactive textbook components for computer science education.
+`sphinx-touchbook` is a Sphinx-oriented port of that general idea: it keeps
+authoring and builds inside Sphinx while Runestone's main project has moved
+away from Sphinx-based authoring and toward PreTeXt-authored books.
+
+The focus of this project is 'Sphinx-native' interactive books and nothing else.
+Runestone is a much more sophisticated environment with instructor resources,
+student tracking, and LMS integration.
+If you want those features then you should consider Runestone as a resource.
+
+## Setup
+
+To build documents Python is required.
+
+Create and activate a virtual environment:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+Install the Python package with test and documentation dependencies:
+
+```bash
+python3 -m pip install --upgrade pip
+python3 -m pip install ".[test,docs]"
+```
+
+To test documents Node.js with `npm` is required.
+
+Install JavaScript test dependencies:
+
+```bash
+npm ci
+```
+
+## Build Documents
+
+Build the author guide as HTML:
+
+```bash
+python3 -m sphinx -b html docs build/authorguide --fail-on-warning
+```
+
+The generated site starts at:
+
+```text
+build/authorguide/index.html
+```
+
+To build LaTeX or PDF requires either a local LaTeX installation
+compatible with Sphinx, or a docker image:
+
+Build LaTeX source locally:
+
+```bash
+python3 -m sphinx -b latex docs build/latex --fail-on-warning
+```
+
+Build the author guide PDF with the Sphinx LaTeX container:
+
+```bash
+docker run --rm \
+  -v "$PWD:/docs" \
+  -w /docs \
+  sphinxdoc/sphinx-latexpdf:latest \
+  sh -c 'python3 -m pip install ".[docs]" && python -m sphinx -M latexpdf docs build/latexpdf --fail-on-warning'
+```
+
+## Run Tests
+
+Run the Python directive and generator tests:
+
+```bash
+python3 -m pytest tests/test_*.py
+```
+
+Run isolated JavaScript component tests:
+
+```bash
+npm run test:web-components
+```
+
+See the author guide in `docs/` for directive syntax, options, examples,
+accessibility notes, and fallback behavior.

sphinx_touchbook-0.1.0/README.md

@@ -0,0 +1,98 @@
+# sphinx-touchbook
+[![Tests](https://img.shields.io/github/actions/workflow/status/daveparillo/sphinx-touchbook/publish-authorguide.yml?branch=main&label=tests)](https://github.com/daveparillo/sphinx-touchbook/actions/workflows/publish-authorguide.yml)
+[![Author Guide](https://img.shields.io/github/actions/workflow/status/daveparillo/sphinx-touchbook/publish-authorguide.yml?branch=main&label=docs)](https://github.com/daveparillo/sphinx-touchbook/actions/workflows/publish-authorguide.yml)
+[![License](https://img.shields.io/github/license/daveparillo/sphinx-touchbook)](LICENSE)
+
+`sphinx-touchbook` is a Sphinx extension project for authors who want
+interactive textbook pages without giving up ordinary Sphinx documents.
+Authors write semantic reStructuredText directives, Sphinx parses them into
+docutils nodes, Python generators render builder-specific output, and
+JavaScript components progressively enhance the generated HTML.
+
+This project is inspired by
+[Runestone Interactive](https://github.com/RunestoneInteractive),
+which pioneered interactive textbook components for computer science education.
+`sphinx-touchbook` is a Sphinx-oriented port of that general idea: it keeps
+authoring and builds inside Sphinx while Runestone's main project has moved
+away from Sphinx-based authoring and toward PreTeXt-authored books.
+
+The focus of this project is 'Sphinx-native' interactive books and nothing else.
+Runestone is a much more sophisticated environment with instructor resources,
+student tracking, and LMS integration.
+If you want those features then you should consider Runestone as a resource.
+
+## Setup
+
+To build documents Python is required.
+
+Create and activate a virtual environment:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+Install the Python package with test and documentation dependencies:
+
+```bash
+python3 -m pip install --upgrade pip
+python3 -m pip install ".[test,docs]"
+```
+
+To test documents Node.js with `npm` is required.
+
+Install JavaScript test dependencies:
+
+```bash
+npm ci
+```
+
+## Build Documents
+
+Build the author guide as HTML:
+
+```bash
+python3 -m sphinx -b html docs build/authorguide --fail-on-warning
+```
+
+The generated site starts at:
+
+```text
+build/authorguide/index.html
+```
+
+To build LaTeX or PDF requires either a local LaTeX installation
+compatible with Sphinx, or a docker image:
+
+Build LaTeX source locally:
+
+```bash
+python3 -m sphinx -b latex docs build/latex --fail-on-warning
+```
+
+Build the author guide PDF with the Sphinx LaTeX container:
+
+```bash
+docker run --rm \
+  -v "$PWD:/docs" \
+  -w /docs \
+  sphinxdoc/sphinx-latexpdf:latest \
+  sh -c 'python3 -m pip install ".[docs]" && python -m sphinx -M latexpdf docs build/latexpdf --fail-on-warning'
+```
+
+## Run Tests
+
+Run the Python directive and generator tests:
+
+```bash
+python3 -m pytest tests/test_*.py
+```
+
+Run isolated JavaScript component tests:
+
+```bash
+npm run test:web-components
+```
+
+See the author guide in `docs/` for directive syntax, options, examples,
+accessibility notes, and fallback behavior.

sphinx_touchbook-0.1.0/docs/accessibility.rst

@@ -0,0 +1,83 @@
+Accessibility And Keyboard Use
+==============================
+
+Touchbook directives use native HTML controls wherever possible. Buttons,
+inputs, text areas, selects, links, and dialogs keep their browser keyboard
+behavior and programmatic labels. This helps assistive technology and lets each
+browser expose controls in the way users expect.
+
+Keyboard Basics
+---------------
+
+Most Touchbook controls follow standard browser behavior:
+
+* ``Tab`` moves forward through focusable controls.
+* ``Shift+Tab`` moves backward through focusable controls.
+* ``Enter`` activates links and most buttons.
+* ``Space`` activates buttons, checkboxes, radio buttons, and similar controls.
+* Arrow keys may move within composite widgets, such as tab groups.
+
+Tab Groups
+----------
+
+The ``tb-group`` directive renders an ARIA tab interface. Only the selected tab
+is in the normal ``Tab`` order. This is intentional and follows the common
+roving-tabindex pattern for tabs.
+
+When focus is on a tab:
+
+* ``ArrowRight`` moves to the next tab.
+* ``ArrowLeft`` moves to the previous tab.
+* ``Home`` moves to the first tab.
+* ``End`` moves to the last tab.
+* ``Tab`` moves into the selected tab panel when that panel contains a
+  focusable control.
+
+For example, if a ``tb-group`` has ``Source`` and ``Rendered`` tabs, ``Tab``
+does not normally move from ``Source`` to ``Rendered``. Use the arrow keys to
+select ``Rendered``. Then use ``Tab`` to enter the rendered content.
+
+Platform Settings
+-----------------
+
+Keyboard navigation can depend on operating system and browser settings. If
+``Tab`` skips buttons or other native controls, check the platform settings
+before assuming the page is broken.
+
+macOS
+   In System Settings, open **Keyboard** and enable full keyboard navigation.
+   Safari also has a browser-specific setting in **Advanced** named
+   **Press Tab to highlight each item on a webpage**.
+
+   When full keyboard access is disabled, macOS browsers may require
+   ``Option+Tab`` or ``Alt+Tab`` to move to buttons and other controls.
+
+Windows
+   Windows browsers usually include buttons in the normal ``Tab`` order. If
+   navigation seems incomplete, check browser accessibility settings and any
+   installed keyboard or assistive-technology utilities. In Microsoft Edge and
+   Chrome, also check whether caret browsing or extension settings are changing
+   keyboard behavior.
+
+Linux
+   Linux behavior depends on the desktop environment, browser, and assistive
+   technology stack. GNOME, KDE, Firefox, Chrome, and Chromium usually include
+   native buttons in the normal ``Tab`` order. If they do not, check desktop
+   keyboard accessibility settings, browser settings, and screen-reader or
+   extension configuration.
+
+Testing Guidance
+----------------
+
+When testing Touchbook content for keyboard accessibility:
+
+* Test with full keyboard navigation enabled.
+* Confirm that every visible control can receive focus.
+* Confirm that visible focus is easy to see.
+* Activate buttons with ``Space`` and ``Enter``.
+* Test ``tb-group`` tabs with arrow keys, not only with ``Tab``.
+* Test the static fallback output when building text or PDF formats.
+
+Touchbook should provide accessible controls and predictable focus behavior.
+Operating system and browser settings can still change how users move through
+native controls.

sphinx_touchbook-0.1.0/docs/components/tb-blank.rst

@@ -0,0 +1,194 @@
+tb-blank
+========
+
+The ``tb-blank`` directive creates a fill-in-the-blank question.
+Authors place one or more ``{{blank}}`` markers in normal Sphinx content.
+Nested ``tb-answer`` blocks define accepted answers, targeted hints for common
+wrong answers, and fallback incorrect feedback.
+
+Synopsis
+--------
+
+The general format of the ``tb-blank`` directive is:
+
+.. code-block:: rst
+
+   .. tb-blank::
+      :optional parameter: value
+
+      + --- Prompt area ---
+      |
+      | question text and optional Sphinx content with {{blank}} markers
+      |
+      + --- Answer area ---
+      |
+      | .. tb-answer:: optional-blank-id
+      |    :match: accepted answer
+      |    :feedback: correct feedback
+      |    :hint: known wrong answer; targeted feedback
+      |    :incorrect: fallback incorrect feedback
+      |
+      + -----------------
+
+Options
+-------
+
+**case-sensitive**
+   ``Flag``. Optional.
+   Require exact case when comparing submitted answers. By default, matching is
+   case-insensitive.
+
+**name**
+   ``String``. Optional.
+   Sphinx reference name for this fill-in-the-blank question.
+   This is a
+   `Docutils common option <https://docutils.sourceforge.io/docs/ref/rst/directives.html#common-options>`__.
+   If omitted, docutils assigns a deterministic generated ID derived from the
+   document and node position.
+
+**preserve-whitespace**
+   ``Flag``. Optional.
+   Preserve leading and trailing whitespace when comparing submitted answers.
+   By default, submitted answers and expected answers are trimmed.
+
+Answer Options
+--------------
+
+Nested ``tb-answer`` blocks support these options:
+
+**feedback**
+   ``String``. Optional.
+   Feedback shown when a submitted answer matches one of the accepted answers.
+
+**hint**
+   ``String``. Optional. Repeatable.
+   Known wrong answer and targeted feedback separated by the first semicolon.
+   For example, ``:hint: 7; Check the assignment in the else block.``.
+
+**incorrect**
+   ``String``. Optional.
+   Feedback shown when the submitted answer does not match an accepted answer
+   or a known wrong answer.
+
+**match**
+   ``String``. Required. Repeatable.
+   Accepted answer. Matching is case-insensitive and trims leading and trailing
+   whitespace unless directive options override those defaults.
+
+**regex**
+   ``Flag``. Optional.
+   Treat ``match`` values as regular expressions.
+
+Accessibility behavior
+----------------------
+
+HTML uses native text inputs and a native button. Result text uses a status
+region so assistive technology can announce feedback after checking.
+
+Fallback behavior
+-----------------
+
+HTML without JavaScript renders the prompt and input fields. Text and
+PDF-oriented builders render each blank as an underline. Answers and feedback
+are not rendered in fallback output.
+
+Examples
+--------
+
+Example 1: Single blank
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. tb-group::
+   :name: blank-ex1-tabs
+
+   .. tb-tab:: Source
+
+      .. code-block:: rst
+
+         .. tb-blank::
+
+            The capital of France is {{blank}}.
+
+            .. tb-answer::
+               :match: Paris
+               :feedback: Correct.
+               :incorrect: Try again.
+
+   .. tb-tab:: Rendered
+
+      .. tb-blank::
+
+         The capital of France is {{blank}}.
+
+         .. tb-answer::
+            :match: Paris
+            :feedback: Correct.
+            :incorrect: Try again.
+
+Example 2: Code reasoning with targeted hints
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. tb-group::
+   :name: blank-ex2-tabs
+
+   .. tb-tab:: Source
+
+      .. code-block:: rst
+
+         .. tb-blank::
+
+            .. code-block:: c
+
+               int main(void) {
+                 int a = 7;
+                 int b = 4;
+
+                 if (a<=b) {
+                   a = 99;
+                 } else {
+                   int t = a;
+                   a = b;
+                   b = t;
+                 }
+                 return a;
+               }
+
+            What value is returned from main? {{blank}}
+
+            .. tb-answer::
+               :match: 4
+               :match: 4.0
+               :feedback: Correct.
+               :hint: 7; No, because the variable a is modified in the else block.
+               :hint: 99; No. Since a is greater than b, line 6 is never executed.
+               :incorrect: Sorry, no. What is happening in the else block?
+
+   .. tb-tab:: Rendered
+
+      .. tb-blank::
+
+         .. code-block:: c
+
+            int main(void) {
+              int a = 7;
+              int b = 4;
+
+              if (a<=b) {
+                a = 99;
+              } else {
+                int t = a;
+                a = b;
+                b = t;
+              }
+              return a;
+            }
+
+         What value is returned from main? {{blank}}
+
+         .. tb-answer::
+            :match: 4
+            :match: 4.0
+            :feedback: Correct.
+            :hint: 7; No, because the variable a is modified in the else block.
+            :hint: 99; No. Since a is greater than b, line 6 is never executed.
+            :incorrect: Sorry, no. What is happening in the else block?