t-doc-common 0.4.dev1__tar.gz → 0.6.dev1__tar.gz

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

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

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

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

{t_doc_common-0.4.dev1 → t_doc_common-0.6.dev1}/.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.6.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: t-doc-common
-Version: 0.4.dev1
+Version: 0.6.dev1
 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.6.dev1/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.6.dev1/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.6.dev1/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.6.dev1}/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.6.dev1/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.6.dev1}/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.6.dev1}/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
   ```
+  ````
+  `````