t-doc-common 0.4.dev1__tar.gz → 0.5__tar.gz

{t_doc_common-0.4.dev1 → t_doc_common-0.5}/.gitignore

@@ -3,10 +3,8 @@
 # SPDX-License-Identifier: MIT
 
 *.orig
-*.sqlite3
 __pycache__
 
-build/
+_build/
 dist/
 tmp/
-*.egg-info/

{t_doc_common-0.4.dev1 → t_doc_common-0.5}/.hgignore

@@ -4,11 +4,9 @@
 
 syntax: glob
 *.orig
-*.sqlite3
 __pycache__
 
 syntax: regexp
-^build/
+^_build/
 ^dist/
 ^tmp/
-^[^/]+\.egg-info/

{t_doc_common-0.4.dev1 → t_doc_common-0.5}/.hgtags

@@ -1,2 +1,4 @@
 267a6c8ad66dde08f2b75d2d82d0d2985ca8f137 0.2
 ea2973414a3779c7ffbed73279ab8d811c795268 0.3
+dcb01efb897d0e04063b92998c17b02b587761c7 0.4
+e4ac6c10dd9194ff48c95d82e462e45bbd651ef1 0.5

{t_doc_common-0.4.dev1 → t_doc_common-0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: t-doc-common
-Version: 0.4.dev1
+Version: 0.5
 Summary: Common functionality for t-doc
 Project-URL: Code, https://github.com/t-docs/common
 Project-URL: Documentation, https://t-doc.org/common/

t_doc_common-0.5/docs/demo/index.md

@@ -0,0 +1,11 @@
+<!-- Copyright 2024 Caroline Blank <caro@c-space.org> -->
+<!-- Copyright 2024 Remy Blank <remy@c-space.org> -->
+<!-- SPDX-License-Identifier: MIT -->
+
+# Demo
+
+```{toctree}
+:maxdepth: 1
+
+sql
+```

t_doc_common-0.5/docs/demo/people.sql

@@ -0,0 +1,11 @@
+create table people (
+    first_name text not null,
+    last_name text not null,
+    height real,
+    favorite_food text
+);
+insert into people values
+    ('Joe', 'Bar', 1.83, null),
+    ('Jack', 'Smith', 1.55, 'burgers'),
+    ('Jim', 'Davis', null, 'pizza'),
+    ('Anthony', 'Miller', 1.78, null);

t_doc_common-0.5/docs/demo/sql.md

@@ -0,0 +1,113 @@
+<!-- Copyright 2024 Caroline Blank <caro@c-space.org> -->
+<!-- Copyright 2024 Remy Blank <remy@c-space.org> -->
+<!-- SPDX-License-Identifier: MIT -->
+
+# SQL
+
+The `{exec} sql` block allows executing SQL directly in the browser. Each block
+is executed in a new, empty database.
+
+## Directive
+
+````{rst:directive} .. {exec}:: language (sql)
+This directive is a `{code-block}` that allows executing the code directly in
+the browser. It supports all the options of `{code-block}`, and a few more
+described below.
+
+{.rubric}
+Options
+```{rst:directive:option} after: name
+:type: text
+References an `{exec}` block to be executed before this block, in the same
+environment. The referenced block can itself have an `:after:` option, forming
+a chain of blocks to execute in the environment.
+```
+```{rst:directive:option} when: value
+:type: click | load | never
+Determines when the block's code is executed: on a click by the user (`click`),
+when the page loads (`load`) or not at all (`never`).
+```
+````
+
+## Database definition
+
+A database can be defined as a named `{exec} sql` block, to be referenced in the
+`:after:` option of other blocks.
+
+```{exec} sql
+:name: sql-countries
+:when: never
+create table countries (
+    country text not null,
+    country_code text not null,
+    dial_code text not null,
+    capital text not null,
+    population int not null,
+    food text
+);
+insert into countries values
+    ('Switzerland', 'CH', '+41', 'Bern', 8776000, 'fondue!'),
+    ('France', 'FR', '+33', 'Paris', 67970000, null),
+    ('Germany', 'DE', '+49', 'Berlin', 83800000, null),
+    ('Italy', 'IT', '+39', 'Rome', 58940000, null),
+    ('Austria', 'AT', '+43', 'Vienna', 9042000, 'Kaiserschmarrn'),
+    ('Lichtenstein', 'LI', '+423', 'Vaduz', 39327, null);
+```
+
+## Queries
+
+The results of the first `select` statement in an `{exec} sql` block are
+displayed as a table.
+
+```{exec} sql
+:after: sql-countries
+:when: load
+select * from countries;
+```
+
+The SQL code can be hidden by adding `:class: hidden`.
+
+```{exec} sql
+:after: sql-countries
+:when: load
+:class: hidden
+select * from countries where country_code = 'CH';
+```
+
+### Empty results
+
+```{exec} sql
+:after: sql-countries
+:when: load
+select * from countries where false;
+```
+
+## Mutations
+
+```{exec} sql
+:after: sql-countries
+:when: load
+update countries set food = 'baguette' where country_code = 'FR';
+select * from countries where country_code = 'FR';
+```
+
+## SQL errors
+
+```{exec} sql
+:when: load
+select * from unknown_table;
+```
+
+## Execution trigger
+
+By default, `{exec} sql` blocks are executed on click (`:when: click`), with
+controls displayed next to the block.
+
+```{exec} sql
+:after: sql-countries
+select * from countries where country_code = 'LI';
+```
+
+They can also be executed immediately on load (`:when: load`) or not at all
+(`:when: never`, useful for database definitions that are referenced by other
+blocks). In these cases, no controls aren displayed.

{t_doc_common-0.4.dev1 → t_doc_common-0.5}/docs/development.md

@@ -4,45 +4,93 @@
 
 # Development
 
+This page describes how to set up t-doc for development. It isn't necessary for
+creating and editing documents.
+
 ## Install
 
 - Install the [required packages](install.md#requirements) for your system.
 
 - Clone the `t-doc/common` repository (substitute `USER` with your username).
+
   ```{code-block} shell-session
   hg clone https://USER@c-space.net/rc/hg/t-doc/common
   cd common
   ```
 
 - Enable git subrepositories.
+
   ```{code-block} shell-session
   echo -e '[subrepos]\ngit:allowed = true\n' >> .hg/hgrc
   ```
 
 - Checkout the subrepositories and activate the `main` bookmark.
+
   ```{code-block} shell-session
   hg checkout main
   ```
 
 - Install the `t-doc-common` package from editable sources.
+
+  `````{tab-set}
+  :sync-group: platform
+  ````{tab-item} Windows
+  :sync: windows
+  ```{code-block} shell-session
+  python -m pip install --editable .
+  ```
+  ````
+  ````{tab-item} macOS
+  :sync: macos
+  ```{code-block} shell-session
+  python -m pip install --user --editable .
+  ```
+  You may have to add `$HOME/.local/bin` to your `PATH`.
+  ````
+  ````{tab-item} Linux
+  :sync: linux
   ```{code-block} shell-session
   python -m pip install --user --editable .
   ```
+  You may have to add `$HOME/.local/bin` to your `PATH`.
+  ````
+  `````
 
 ## Upgrade
 
 - Pull missing changesets from the `t-doc/common` repository.
+
   ```{code-block} shell-session
   cd common
   hg pull
   ```
 
 - Update to the branch head.
+
   ```{code-block} shell-session
   hg update --check
   ```
 
 - Upgrade the `t-doc-common` package metadata and any out-of-date dependencies.
+
+  `````{tab-set}
+  :sync-group: platform
+  ````{tab-item} Windows
+  :sync: windows
+  ```{code-block} shell-session
+  python -m pip install --upgrade --editable .
+  ```
+  ````
+  ````{tab-item} macOS
+  :sync: macos
+  ```{code-block} shell-session
+  python -m pip install --user --upgrade --editable .
+  ```
+  ````
+  ````{tab-item} Linux
+  :sync: linux
   ```{code-block} shell-session
   python -m pip install --user --upgrade --editable .
   ```
+  ````
+  `````

t_doc_common-0.5/docs/edit.md

@@ -0,0 +1,106 @@
+<!-- Copyright 2024 Caroline Blank <caro@c-space.org> -->
+<!-- Copyright 2024 Remy Blank <remy@c-space.org> -->
+<!-- SPDX-License-Identifier: MIT -->
+
+# Create & edit documents
+
+## Check out a repository
+
+Documents are grouped into **repositories**, which represent the unit of
+deployment. Each document repository is tracked as a Mercurial repository. A
+repository can be checked out with (substitute `USER` with your username, and
+`REPO` with the name of the repository):
+
+```{code-block} shell-session
+hg checkout https://USER@c-space.net/rc/hg/t-doc/REPO
+```
+
+The typical structure of a document repository is shown below. The source files
+are located below the `docs` directory.
+
+```{code-block}
+:class: line-height-normal
+├── .github
+│   └── workflows
+│       └── publish.yml       A workflow to publish the repository
+├── docs
+│   ├── conf.py               The Sphinx configuration
+│   ├── index.md              The main index page
+│   └── ...                   The source documents
+├── .gitignore
+├── .hgignore
+├── LICENSE.txt
+├── README.md
+├── serve.bat                 A script to run the local server on Windows
+└── serve.desktop             A desktop entry to run the local server on Linux
+```
+
+## Edit documents
+
+- **Run the local server.**
+
+  `````{tab-set}
+  :sync-group: platform
+  ````{tab-item} Windows
+  :sync: windows
+  Double-click the file `serve.bat` in the repository directory.
+  ````
+  ````{tab-item} macOS
+  :sync: macos
+  Open a terminal, change to the repository directory, and run:
+  ```{code-block} shell-session
+  tdoc serve
+  ```
+  ````
+  ````{tab-item} Linux
+  :sync: linux
+  Double-click the file `serve.desktop` in the repository directory.
+
+  Alternatively, open a terminal, change to the repository directory, and run:
+  ```{code-block} shell-session
+  tdoc serve
+  ```
+  ````
+  `````
+
+  The server renders the source files into HTML, and serves the result over
+  HTTP.
+
+  ```{code-block} text
+  Running Sphinx v8.0.2
+  loading translations [fr]... done
+  making output directory... done
+  (...)
+  build succeeded.
+
+  The HTML pages are in _build\serve-1724331687766143000\html.
+  Serving at <http://[::1]:8000/>
+  ```
+
+- **Navigate** to [http://localhost:8000/](http://localhost:8000/) to view the
+  generated pages.
+
+- **Create and edit documents** in the `docs` directory. This can be done with
+  any plain text editor. The local server watches the source files and
+  **automatically rebulids the HTML when a file changes**. Reload the page in
+  the browser to view the updated output. If a build fails, the errors can be
+  found in the terminal.
+
+- **Stop the local server** with {kbd}`Ctrl+C` in the terminal, or by closing
+  the terminal window.
+
+- Don't forget to **commit changes frequently**.
+
+## Deploy documents
+
+To deploy the repository to `tdoc.org`, make sure that all changes have been
+committed (and that new files have been added with Mercurial), then push the
+changes to the server.
+
+```{code-block} shell-session
+hg push
+```
+
+The changes should be live at `https://t-doc.org/REPO` within a few minutes. If
+the build fails, GitHub will send you an email notification. It contains a link
+to the build log, which should allow figuring out what went wrong.

{t_doc_common-0.4.dev1 → t_doc_common-0.5}/docs/index.md

@@ -10,5 +10,7 @@ This documentation describes how to install and use t-doc.
 :maxdepth: 1
 
 install
+edit
 development
+demo/index
 ```

{t_doc_common-0.4.dev1 → t_doc_common-0.5}/docs/install.md

@@ -15,34 +15,60 @@ t-doc requires the following software to be installed:
 ### Windows
 
 - Install [Python](https://www.python.org/).
+
   ```{code-block} shell-session
   winget install --id Python.Python.3.12
   ```
 
+  - Check that Python can be launched from the command-line, by running:
+
+    ```{code-block} shell-session
+    python
+    ```
+
+    If this opens the Microsoft Store, open Windows settings, search for "App
+    execution aliases", and disable the "App Installer" entries for `python.exe`
+    and `python3.exe`.
+
 - Install [Graphviz](https://graphviz.org/). The installer must be run
   interactively and the **"Add Graphviz to the system PATH for all users"**
   option must be enabled.
+
   ```{code-block} shell-session
   winget install --id Graphviz.Graphviz --interactive
   ```
 
 - Install [TortoiseHg](https://tortoisehg.bitbucket.io/).
+
   ```{code-block} shell-session
   winget install --id TortoiseHg.TortoiseHg
   ```
 
-  ```{admonition} TODO
-  TODO: Describe how to update .hgrc to configure the name and email address.
-  ```
+  - Open the TortoiseHg settings, go to your user's global settings, then click
+    "Edit file" and add the following to the configuration (substitute `FIRST`
+    and `LAST` with your first and last name, and `EMAIL` with your email
+    address, e.g. `Joe Smith <joe@example.com>`):
+
+    ```ini
+    [ui]
+    username = FIRST LAST <EMAIL>
+    ```
 
 - (Optional, Windows 10) Install
   [Windows Terminal](https://github.com/microsoft/terminal) (it's already
   installed on Windows 11 and later).
+
   ```{code-block} shell-session
   winget install --id Microsoft.WindowsTerminal
   ```
 
-### Linux, macOS
+### macOS
+
+- Install [Python](https://www.python.org/), [Graphviz](https://graphviz.org/)
+  and [Mercurial](https://www.mercurial-scm.org/) either by hand or through a
+  package manager like [Homebrew](https://brew.sh/).
+
+### Linux
 
 - Install [Python](https://www.python.org/), [Graphviz](https://graphviz.org/)
   and [Mercurial](https://www.mercurial-scm.org/) through your system's package
@@ -53,13 +79,53 @@ t-doc requires the following software to be installed:
 - Install the [required packages](#requirements).
 
 - Install the `t-doc-common` package.
+
+  `````{tab-set}
+  :sync-group: platform
+  ````{tab-item} Windows
+  :sync: windows
+  ```{code-block} shell-session
+  python -m pip install t-doc-common
+  ```
+  ````
+  ````{tab-item} macOS
+  :sync: macos
+  ```{code-block} shell-session
+  python -m pip install --user t-doc-common
+  ```
+  You may have to add `$HOME/.local/bin` to your `PATH`.
+  ````
+  ````{tab-item} Linux
+  :sync: linux
   ```{code-block} shell-session
   python -m pip install --user t-doc-common
   ```
+  You may have to add `$HOME/.local/bin` to your `PATH`.
+  ````
+  `````
 
 ## Upgrade
 
 - Upgrade the `t-doc-common` package and any out-of-date dependencies.
+
+  `````{tab-set}
+  :sync-group: platform
+  ````{tab-item} Windows
+  :sync: windows
+  ```{code-block} shell-session
+  python -m pip install --upgrade t-doc-common
+  ```
+  ````
+  ````{tab-item} macOS
+  :sync: macos
+  ```{code-block} shell-session
+  python -m pip install --user --upgrade t-doc-common
+  ```
+  ````
+  ````{tab-item} Linux
+  :sync: linux
   ```{code-block} shell-session
   python -m pip install --user --upgrade t-doc-common
   ```
+  ````
+  `````

t_doc_common-0.5/serve.bat

@@ -0,0 +1,2 @@
+@echo off
+tdoc serve

t_doc_common-0.5/serve.desktop

@@ -0,0 +1,10 @@
+[Desktop Entry]
+Name=Serve
+Type=Application
+GenericName=Start a local server
+Comment=
+Icon=document-preview
+Exec=cd "$(dirname "%k")" && "${HOME}/.local/bin/tdoc" serve
+Path=
+Terminal=true
+StartupNotify=false

{t_doc_common-0.4.dev1 → t_doc_common-0.5}/tdoc/common/__init__.py

@@ -3,17 +3,18 @@
 # SPDX-License-Identifier: MIT
 
 import pathlib
+import re
 
 from docutils import nodes
+from docutils.parsers.rst import directives
 from sphinx.directives.code import CodeBlock
 from sphinx.util import logging
 
 __project__ = 't-doc-common'
-__version__ = '0.4.dev1'
+__version__ = '0.5'
 
 _common = pathlib.Path(__file__).absolute().parent
 _root = _common.parent.parent
-makefile = str(_common / 'common.mk')
 
 _log = logging.getLogger(__name__)
 
@@ -34,9 +35,11 @@ def setup(app):
 
     app.add_html_theme('t-doc', str(_common))
     app.add_directive('exec', Exec)
+    app.add_node(ExecBlock, html=(visit_ExecBlock, depart_ExecBlock))
 
     app.connect("config-inited", on_config_inited)
     app.connect('builder-inited', on_builder_inited)
+    app.connect('doctree-resolved', check_after_references)
     app.connect('html-page-context', on_html_page_context)
 
     return {
@@ -61,6 +64,7 @@ def on_config_inited(app, config):
 
 
 def on_builder_inited(app):
+    # Add our own static paths.
     app.config.html_static_path.append(str(_common / 'static'))
     sw = _root / 'ext' / 'sqlite-wasm' / 'sqlite-wasm'
     if (sw / 'jswasm').is_dir():
@@ -79,13 +83,25 @@ def on_html_page_context(app, page, template, context, doctree):
         # TODO: Work around inability to specify headers on GitHub Pages
 
 
+def format_data_attrs(translator, /, **kwargs):
+    return ' '.join(f'data-tdoc-{k}="{translator.attval(v)}"'
+                    for k, v in sorted(kwargs.items()) if v is not None)
+
+
+class ExecBlock(nodes.literal_block): pass
+
+
 class Exec(CodeBlock):
-    # TODO: :after: option
-    # TODO: :show: option
-    # TODO: :immediate: or :run:
+    # TODO: :include:
+
+    option_spec = CodeBlock.option_spec | {
+        'after': directives.unchanged,
+        'when': lambda c: directives.choice(c, ('click', 'load', 'never')),
+    }
+
     @staticmethod
     def match_node(lang=None):
-        return lambda n: isinstance(n, nodes.literal_block) \
+        return lambda n: isinstance(n, ExecBlock) \
                          and 'tdoc-exec' in n['classes'] \
                          and (lang is None or n.get('language') == lang)
 
@@ -93,6 +109,46 @@ class Exec(CodeBlock):
         res = super().run()
         for node in res:
             for n in node.findall(nodes.literal_block):
-                n['classes'] += ['tdoc-exec']
+                self._update_node(node)
         # _log.info("res: %s", res, color='yellow')
         return res
+
+    def _update_node(self, node):
+        node.__class__ = ExecBlock
+        node.tagname = node.__class__.__name__
+        node['classes'] += ['tdoc-exec']
+        if after := self.options.get('after'):
+            node['after'] = after
+        node['when'] = self.options.get('when', 'click')
+
+
+def check_after_references(app, doctree, docname):
+    nodes = list(doctree.findall(Exec.match_node('sql')))
+    names = set()
+    for n in nodes:
+        names.update(n['names'])
+    for n in nodes:
+        after = n.get('after')
+        if after and after not in names:
+            doctree.reporter.error(
+                f"'exec': Unknown :after: reference: {after}", base_node=n)
+
+
+div_attrs_re = re.compile(r'(?s)^(<div[^>]*)(>.*)$')
+
+
+def visit_ExecBlock(self, node):
+    try:
+        return self.visit_literal_block(node)
+    except nodes.SkipNode:
+        attrs = format_data_attrs(self, after=node.get('after'),
+                                  when=node.get('when'))
+        if attrs:
+            def subst(m):
+                return f'{m.group(1)} {attrs}{m.group(2)}'
+            self.body[-1] = div_attrs_re.sub(subst, self.body[-1], 1)
+        raise
+
+
+def depart_ExecBlock(self, node):
+    return self.depart_literal_block(node)

{t_doc_common-0.4.dev1 → t_doc_common-0.5}/tdoc/common/cli.py

@@ -208,6 +208,7 @@ class ServerBase(server.ThreadingHTTPServer):
             self.cfg.stderr.write(f"Scan: {e}\n")
         mtime = 0
         for path in itertools.chain([self.cfg.source], self.cfg.watch):
+            # TODO: Exclude files in __pycache__
             for base, dirs, files in path.walk(on_error=on_error):
                 for file in files:
                     try:

{t_doc_common-0.4.dev1 → t_doc_common-0.5}/tdoc/common/defaults.py

@@ -9,6 +9,7 @@ smartquotes = False
 primary_domain = None
 nitpicky = True
 exclude_patterns = ['_build', '.DS_Store', 'Thumbs.db']
+highlight_language = 'text'
 
 extensions = [
     'myst_parser',
@@ -34,6 +35,10 @@ extensions = [
     'tdoc.common',
 ]
 
+suppress_warnings = [
+    'myst.strikethrough',  # Only supported for HTML, but that's all we want
+]
+
 # Extension options.
 graphviz_output_format = 'svg'
 todo_include_todos = True
@@ -41,6 +46,8 @@ todo_include_todos = True
 # MyST options.
 myst_enable_extensions = {
     'amsmath',
+    'attrs_block',
+    'attrs_inline',
     'colon_fence',
     'deflist',
     'dollarmath',

t_doc_common-0.5/tdoc/common/static/styles/t-doc.css

@@ -0,0 +1,100 @@
+/* Copyright 2024 Caroline Blank <caro@c-space.org> */
+/* Copyright 2024 Remy Blank <remy@c-space.org> */
+/* SPDX-License-Identifier: MIT */
+
+:not(#_).hidden {
+    display: none;
+}
+:not(#_).line-height-normal .highlight pre {
+    line-height: normal;
+}
+
+/* Set the maximum width of sidebars instead of a fixed width. */
+div.sidebar, aside.sidebar {
+    max-width: 40%;
+    width: inherit;
+}
+
+/* Invert the even and odd row colors in tables, so that the first row below the
+   header has a different color than the header. */
+.table tbody tr:nth-child(even) {
+    background-color: var(--pst-color-table-row-zebra-low-bg);
+}
+.table tbody tr:nth-child(odd) {
+    background-color: var(--pst-color-table-row-zebra-high-bg);
+}
+.table tbody tr:hover {
+    background-color: var(--pst-color-table-row-hover-bg);
+}
+
+/* Execution controls */
+div[class*=highlight-].tdoc-exec {
+    flex-direction: row;
+}
+div.tdoc-exec div.highlight {
+    flex-basis: 100%;
+}
+div.tdoc-exec-controls {
+    display: flex;
+    flex-direction: column;
+    margin-left: 0.3rem;
+}
+div.tdoc-exec-controls button {
+    aspect-ratio: 1;
+    border-radius: 0.25rem;
+    padding: 0.3rem;
+    border: 1px solid var(--pst-color-border);
+    background-color: var(--pst-color-surface);
+    font: var(--fa-font-solid);
+    transition: background-color .3s;
+}
+div.tdoc-exec-controls button:hover {
+    background-color: var(--pst-color-shadow);
+}
+div.tdoc-exec-controls * {
+    margin-top: 0.3rem;
+}
+div.tdoc-exec-controls *:first-child {
+    margin-top: 0;
+}
+div.tdoc-exec-controls button.tdoc-exec-run::before {
+    content: '\f04b';
+}
+div.tdoc-exec-controls button.tdoc-exec-reset::before {
+    content: '\f2ea';
+}
+
+/* SQL execution results */
+.table tbody tr:nth-child(odd).tdoc-no-results {
+    background: repeating-linear-gradient(-45deg,
+        var(--pst-color-table-row-zebra-low-bg) 0px 2px,
+        var(--pst-color-table-row-zebra-high-bg) 2px 20px);
+}
+.tdoc-error {
+    margin-bottom: 1rem;
+    border: 1px solid var(--pst-color-danger);
+    padding: 0.5rem;
+    background: repeating-linear-gradient(-45deg,
+        var(--pst-color-table-row-zebra-low-bg) 0px 2px,
+        var(--pst-color-table-row-zebra-high-bg) 2px 20px);
+}
+
+/* Prevent the wrapper background from being visible if the wrapper is larger
+   than its content. */
+.highlight.highlight.highlight {
+    background: none;
+}
+
+/* Fix the gap left by pydata_sphinx_theme between the table and the
+   scrollbar. */
+div.pst-scrollable-table-container {
+    margin-bottom: 1rem;
+}
+.table {
+    margin-bottom: 0;
+}
+
+/* Reduce the bottom margin of directive definition list options. */
+dl[class]:not(.option-list,.field-list,.footnote,.glossary,.simple):not(._) {
+    margin-bottom: 1rem;
+}

t_doc_common-0.5/tdoc/common/static/tdoc-sql.js

@@ -0,0 +1,173 @@
+// Copyright 2024 Caroline Blank <caro@c-space.org>
+// Copyright 2024 Remy Blank <remy@c-space.org>
+// SPDX-License-Identifier: MIT
+
+import {default as sqlite3_init} from './jswasm/sqlite3-worker1-promiser.mjs';
+
+function waitLoaded() {
+    return new Promise(resolve => {
+        if (document.readyState !== 'loading') {
+            resolve();
+        } else if (document.addEventListener) {
+            document.addEventListener('DOMContentLoaded', resolve);
+        } else {
+            document.attachEvent('onreadystatechange', () => {
+                if (document.readyState === 'interactive') resolve();
+            });
+        }
+    });
+}
+
+function text(value) {
+    return document.createTextNode(value);
+}
+
+function element(html) {
+    const t = document.createElement('template');
+    t.innerHTML = html.trim();
+    return t.content.firstChild;
+}
+
+const promiser = await sqlite3_init({
+    // debug: console.debug,
+});
+
+class Database {
+    static async config() {
+        return (await promiser('config-get', {})).result;
+    }
+
+    static async open(filename) {
+        let {dbId} = await promiser('open', {filename});
+        return new Database(dbId);
+    }
+
+    constructor(dbId) {
+        this.dbId = dbId;
+    }
+
+    async close() {
+        if (this.dbId) {
+            // TODO: Check if "unlink" makes any difference
+            await promiser('close', {dbId: this.dbId, unlink: true});
+            delete this.dbId;
+        }
+    }
+
+    async exec(sql, on_result) {
+        // TODO: Check if other args could be useful, e.g. for splitting a
+        // script into multiple statements
+        await promiser('exec', {dbId: this.dbId, sql, callback: on_result});
+    }
+}
+
+let db_num = 0;
+
+async function execute(exec) {
+    // Compute the chain of nodes to execute.
+    const nodes = [];
+    for (let node = exec; node;) {
+        if (node.classList.contains('tdoc-exec')) {
+            nodes.push(node);
+            node = document.getElementById(node.dataset.tdocAfter)
+        } else {  // Secondary name as a nested <span>
+            node = node.parentNode;
+        }
+    }
+    nodes.reverse();
+
+    removeResults(exec);
+    let results, tbody;
+    const db = await Database.open(`file:db-${db_num++}?vfs=memdb`);
+    try {
+        for (const [i, node] of nodes.entries()) {
+            const pre = node.querySelector('pre');
+            if (!pre) {
+                console.error("<pre> element not found in node ", node);
+                continue;
+            }
+            await db.exec(pre.innerText, res => {
+                if (res.columnNames.length === 0) return;
+                if (i < nodes.length - 1) return;
+                if (!results) {
+                    results = element(`\
+<div class="pst-scrollable-table-container tdoc-exec-output">\
+<table class="table"><thead><tr></tr></thead><tbody></tbody></table>\
+</div>`);
+                    const tr = results.querySelector('tr');
+                    for (const col of res.columnNames) {
+                        const th = tr.appendChild(element(
+                            `<th class="text-center"></th>`));
+                        th.appendChild(text(col));
+                    }
+                    tbody = results.querySelector('tbody');
+                }
+                if (res.row) {
+                    const tr = tbody.appendChild(element(`<tr></tr>`));
+                    for (const val of res.row) {
+                        tr.appendChild(element(`<td class="text-center"></td>`))
+                            .appendChild(val === null ?
+                                         element(`<code>NULL</code>`) :
+                                         text(val));
+                    }
+                } else if (tbody.children.length === 0) {
+                    tbody.appendChild(element(`\
+<tr class="tdoc-no-results">\
+<td colspan="${res.columnNames.length}">No results</td>\
+</tr>`))
+                }
+            });
+        }
+        if (results) exec.after(results);
+    } catch (e) {
+        let msg;
+        if (e.dbId === db.dbId) {
+            msg = /^(SQLITE_ERROR: sqlite3 result code \d+: )?(.*)$/
+                    .exec(e.result.message)[2]
+        } else {
+            msg = e.toString();
+        }
+        results = element(`\
+<div class="tdoc-exec-output tdoc-error"><strong>Error:</strong></div>`);
+        results.appendChild(text(` ${msg}`));
+        exec.after(results);
+    } finally {
+        await db.close();
+    }
+}
+
+async function tryExecute(exec) {
+    try {
+        await execute(exec);
+    } catch (e) {
+        console.error(e);
+    }
+}
+
+function removeResults(exec) {
+    for (;;) {
+        const next = exec.nextElementSibling;
+        if (!next || !next.classList.contains('tdoc-exec-output')) break;
+        next.parentNode.removeChild(next);
+    }
+}
+
+await waitLoaded();
+console.info("SQLite version:", (await Database.config()).version.libVersion);
+
+for (const exec of document.querySelectorAll('div.tdoc-exec.highlight-sql')) {
+    const when = exec.dataset.tdocWhen;
+    if (when === 'load') {
+        tryExecute(exec);  // Intentionally don't await
+    } else if (when === 'click') {
+        const controls = exec.appendChild(element(`\
+<div class="tdoc-exec-controls">\
+<button class="tdoc-exec-run" title="Run"></button>\
+<button class="tdoc-exec-reset" title="Reset"></button>\
+</div>`));
+        controls.querySelector('.tdoc-exec-run').addEventListener(
+            'click', async () => { await tryExecute(exec); });
+        controls.querySelector('.tdoc-exec-reset').addEventListener(
+            'click', () => { removeResults(exec); });
+    }
+}

t_doc_common-0.4.dev1/tdoc/common/common.mk

@@ -1,52 +0,0 @@
-# Copyright 2024 Caroline Blank <caro@c-space.org>
-# Copyright 2024 Remy Blank <remy@c-space.org>
-# SPDX-License-Identifier: MIT
-
-# Configuration.
-COLOR ?= 1
-SPHINX_OPTS ?= --jobs=auto --fail-on-warning
-SPHINX_BUILD ?= sphinx-build
-SOURCE ?= docs
-BUILD ?= docs/_build
-
-# ANSI escape codes.
-_V := $(if $(VERBOSE:0=),,@)
-_ANSI = $(if $(COLOR:0=),\e[$(1)m)
-_NORM := $(call _ANSI,39)
-_BLACK := $(call _ANSI,30)
-_RED := $(call _ANSI,31)
-_GREEN := $(call _ANSI,32)
-_YELLOW := $(call _ANSI,33)
-_BLUE := $(call _ANSI,34)
-_MAGENTA := $(call _ANSI,35)
-_CYAN := $(call _ANSI,36)
-_GREY := $(call _ANSI,37)
-_DGREY := $(call _ANSI,90)
-_LRED := $(call _ANSI,91)
-_LGREEN := $(call _ANSI,92)
-_LYELLOW := $(call _ANSI,93)
-_LBLUE := $(call _ANSI,94)
-_LMAGENTA := $(call _ANSI,95)
-_LCYAN := $(call _ANSI,96)
-_WHITE := $(call _ANSI,97)
-
-.PHONY: default
-default: help
-
-.PHONY: help
-help:
-	$(_V)echo -e "$(_WHITE)Make targets:$(_NORM)"
-	$(_V)echo -e "  $(_LBLUE)serve$(_NORM): Build the $(_LBLUE)html$(_NORM) target, then serve the result on http://localhost:8000"
-	$(_V)echo -e
-	$(_V)PYTHONPATH="$(PYTHONPATH)" $(SPHINX_BUILD) -M help \
-		"$(SOURCE)" "$(BUILD)" $(SPHINX_OPTS) $(O)
-
-.PHONY: serve
-serve: html
-	$(_V)echo -e "$(_WHITE)Serving:$(_NORM) $(_LBLUE)http://localhost:8000$(_NORM)"
-	$(_V)PYTHONPATH="$(PYTHONPATH)" $(PYTHON) -m http.server \
-		--bind=localhost --directory="$(BUILD)/html"
-
-%:
-	$(_V)PYTHONPATH="$(PYTHONPATH)" $(SPHINX_BUILD) -M $@ \
-		"$(SOURCE)" "$(BUILD)" $(SPHINX_OPTS) $(O)

t_doc_common-0.4.dev1/tdoc/common/static/styles/t-doc.css

@@ -1,22 +0,0 @@
-/* Copyright 2024 Caroline Blank <caro@c-space.org> */
-/* Copyright 2024 Remy Blank <remy@c-space.org> */
-/* SPDX-License-Identifier: MIT */
-
-.hidden {
-    display: none !important;
-}
-
-/* Set the maximum width of sidebars instead of a fixed width. */
-div.sidebar, aside.sidebar {
-    max-width: 40%;
-    width: inherit;
-}
-
-/* Fix the gap left by pydata_sphinx_theme between the table and the
-   scrollbar. */
-div.pst-scrollable-table-container {
-    margin-bottom: 1rem;
-}
-.table {
-    margin-bottom: 0;
-}

t_doc_common-0.4.dev1/tdoc/common/static/tdoc-sql.js

@@ -1,141 +0,0 @@
-// Copyright 2024 Caroline Blank <caro@c-space.org>
-// Copyright 2024 Remy Blank <remy@c-space.org>
-// SPDX-License-Identifier: MIT
-
-import {default as sqlite3_init} from './jswasm/sqlite3-worker1-promiser.mjs';
-
-function waitLoaded() {
-    return new Promise(resolve => {
-        if (document.readyState !== 'loading') {
-            resolve();
-        } else if (document.addEventListener) {
-            document.addEventListener('DOMContentLoaded', resolve);
-        } else {
-            document.attachEvent('onreadystatechange', () => {
-                if (document.readyState === 'interactive') resolve();
-            });
-        }
-    });
-}
-
-function text(value) {
-    return document.createTextNode(value);
-}
-
-function addChild(parent, tag) {
-    const el = document.createElement(tag);
-    parent.appendChild(el);
-    return el;
-}
-
-const promiser = await sqlite3_init({
-    // debug: console.debug,
-});
-
-class Database {
-    static async config() {
-        return (await promiser('config-get', {})).result;
-    }
-
-    static async open(filename) {
-        // TODO: Pass name and vfs separately
-        let {dbId} = await promiser('open', {filename});
-        return new Database(dbId);
-    }
-
-    constructor(dbId) {
-        this.dbId = dbId;
-    }
-
-    async close() {
-        if (this.dbId) {
-            // TODO: Check if "unlink" makes any difference
-            await promiser('close', {dbId: this.dbId, unlink: true});
-            delete this.dbId;
-        }
-    }
-
-    async exec(sql, on_result) {
-        // TODO: Check if final result has anything useful
-        // TODO: Check if other args could be useful, e.g. for splitting a
-        // script into multiple statements
-        await promiser('exec', {dbId: this.dbId, sql, callback: on_result});
-    }
-
-    async *query(sql) {
-        let notify, queue;
-        let promise = new Promise(resolve => { notify = resolve; });
-        const exec = this.exec(sql, res => {
-            if (queue) {
-                queue.push(res);
-            } else {
-                queue = [res]
-                notify(queue);
-                promise = new Promise(resolve => { notify = resolve; });
-            }
-        });
-        let done = false;
-        while (!done) {
-            const q = await promise;
-            queue = undefined;
-            for (const res of q) {
-                done = !res.row;
-                if (done) break;
-                yield res;
-            }
-        }
-        await exec;
-    }
-}
-
-async function execute(exec) {
-    const pre = exec.querySelector('pre');
-    if (!pre) {
-        console.error("<pre> element not found");
-        return;
-    }
-    // TODO: Find dependencies
-    const sql = pre.innerText;
-    let results, tbody;
-    const db = await Database.open('file:db?vfs=memdb');
-    try {
-        // TODO: Execute dependencies
-        // TODO: Report errors in output
-        for await (const res of db.query(sql)) {
-            if (!results) {
-                // TODO: Remove previous result table
-                results = document.createElement('div');
-                results.classList.add('pst-scrollable-table-container',
-                                      'tdoc-sql-results');
-                const table = addChild(results, 'table');;
-                table.classList.add('table');
-                const thead = addChild(table, 'thead');
-                const tr = addChild(thead, 'tr');
-                tr.classList.add('row-odd');
-                for (const col of res.columnNames) {
-                    const th = addChild(tr, 'th')
-                    th.classList.add('text-center');
-                    th.appendChild(text(col));
-                }
-                tbody = addChild(table, 'tbody');
-            }
-            const tr = addChild(tbody, 'tr');
-            tr.classList.add(res.rowNumber % 2 === 0 ? 'row-odd' : 'row-even');
-            for (const val of res.row) {
-                const td = addChild(tr, 'td')
-                td.classList.add('text-center');
-                td.appendChild(text(val));
-            }
-        }
-        if (results) exec.after(results);
-    } finally {
-        await db.close();
-    }
-}
-
-await waitLoaded();
-console.info("SQLite version:", (await Database.config()).version.libVersion);
-
-for (const el of document.querySelectorAll('div.tdoc-exec.highlight-sql')) {
-    await execute(el);
-}

{t_doc_common-0.4.dev1 → t_doc_common-0.5}/tdoc/common/theme.toml

@@ -1,6 +1,6 @@
 [theme]
 inherit = "sphinx_book_theme"
 stylesheets = [
-    "styles/t-doc.css",
     "styles/sphinx-book-theme.css",
+    "styles/t-doc.css",
 ]