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

t_doc_common-0.4/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+# Copyright 2024 Caroline Blank <caro@c-space.org>
+# Copyright 2024 Remy Blank <remy@c-space.org>
+# SPDX-License-Identifier: MIT
+
+name: Publish
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  deploy:
+    uses: t-doc-org/common/.github/workflows/deploy-github-pages.yml@main
+    secrets: inherit

t_doc_common-0.4/.hgtags

@@ -0,0 +1,3 @@
+267a6c8ad66dde08f2b75d2d82d0d2985ca8f137 0.2
+ea2973414a3779c7ffbed73279ab8d811c795268 0.3
+dcb01efb897d0e04063b92998c17b02b587761c7 0.4

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

@@ -1,8 +1,9 @@
 Metadata-Version: 2.3
 Name: t-doc-common
-Version: 0.3.dev1
+Version: 0.4
 Summary: Common functionality for t-doc
 Project-URL: Code, https://github.com/t-docs/common
+Project-URL: Documentation, https://t-doc.org/common/
 Project-URL: Homepage, https://t-doc.org/
 Author-email: Remy Blank <remy@c-space.org>, Caroline Blank <caro@c-space.org>
 License: Copyright 2024 Caroline Blank <caro@c-space.org>
@@ -45,15 +46,17 @@ Requires-Dist: sphinx-design>=0.6.0
 Requires-Dist: sphinx-exercise>=0.4.1
 Requires-Dist: sphinx-proof>=0.1.3
 Requires-Dist: sphinx-togglebutton>=0.3.2
-Requires-Dist: sphinx<8,>=7.4.7
+Requires-Dist: sphinx>=8.0.2
 Description-Content-Type: text/markdown
 
 <!-- Copyright 2024 Caroline Blank <caro@c-space.org> -->
 <!-- Copyright 2024 Remy Blank <remy@c-space.org> -->
 <!-- SPDX-License-Identifier: MIT -->
 
-# t-doc - Base commune
+# t-doc - Common
 
-Ce package contient la fonctionnalité commune aux documents basés sur t-doc.
+[![Publish](https://github.com/t-doc-org/common/actions/workflows/publish.yml/badge.svg)](https://github.com/t-doc-org/common/actions/workflows/publish.yml)
 
-Ce logiciel est distribué sous la licence [MIT](LICENSE.txt).
+This package contains the common functionality for documents based on t-doc.
+
+This software is distributed under the [MIT](LICENSE.txt) license.

t_doc_common-0.4/README.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 -->
+
+# t-doc - Common
+
+[![Publish](https://github.com/t-doc-org/common/actions/workflows/publish.yml/badge.svg)](https://github.com/t-doc-org/common/actions/workflows/publish.yml)
+
+This package contains the common functionality for documents based on t-doc.
+
+This software is distributed under the [MIT](LICENSE.txt) license.

t_doc_common-0.4/docs/conf.py

@@ -0,0 +1,18 @@
+# Copyright 2024 Caroline Blank <caro@c-space.org>
+# Copyright 2024 Remy Blank <remy@c-space.org>
+# SPDX-License-Identifier: MIT
+
+import time
+
+from tdoc.common.defaults import *
+
+project = "t-doc"
+copyright = f"{time.strftime('%Y')} Remy Blank"
+license = 'MIT'
+language = 'en'
+
+keep_warnings = True
+
+html_theme_options = {
+    'repository_url': 'https://github.com/t-doc-org/common',
+}

t_doc_common-0.4/docs/development.md

@@ -0,0 +1,96 @@
+<!-- Copyright 2024 Caroline Blank <caro@c-space.org> -->
+<!-- Copyright 2024 Remy Blank <remy@c-space.org> -->
+<!-- SPDX-License-Identifier: MIT -->
+
+# 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.4/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/docs/index.md

@@ -0,0 +1,15 @@
+<!-- Copyright 2024 Caroline Blank <caro@c-space.org> -->
+<!-- Copyright 2024 Remy Blank <remy@c-space.org> -->
+<!-- SPDX-License-Identifier: MIT -->
+
+# t-doc
+
+This documentation describes how to install and use t-doc.
+
+```{toctree}
+:maxdepth: 1
+
+install
+edit
+development
+```

t_doc_common-0.4/docs/install.md

@@ -0,0 +1,121 @@
+<!-- Copyright 2024 Caroline Blank <caro@c-space.org> -->
+<!-- Copyright 2024 Remy Blank <remy@c-space.org> -->
+<!-- SPDX-License-Identifier: MIT -->
+
+# Install & upgrade
+
+## Requirements
+
+t-doc requires the following software to be installed:
+
+- [Python](https://www.python.org/) 3.12 or later
+- [Graphviz](https://graphviz.org/), for `{graphviz}` directives
+- [Mercurial](https://www.mercurial-scm.org/), for managing source files
+
+### Windows
+
+- Install [Python](https://www.python.org/).
+
+  ```{code-block} shell-session
+  winget install --id Python.Python.3.12
+  ```
+
+- 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
+  ```
+
+  - 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
+  ```
+
+### 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
+  manager.
+
+## Install
+
+- 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.3.dev1 → t_doc_common-0.4}/pyproject.toml

@@ -10,6 +10,7 @@ authors = [
     {name = "Caroline Blank", email = "caro@c-space.org"},
 ]
 urls.Code = "https://github.com/t-docs/common"
+urls.Documentation = "https://t-doc.org/common/"
 urls.Homepage = "https://t-doc.org/"
 readme = "README.md"
 license.file = "LICENSE.txt"
@@ -28,7 +29,7 @@ requires-python = ">=3.12"
 dependencies = [
     "colorama>=0.4.6; sys_platform == 'win32'",
     "myst-parser>=3.0.1",
-    "Sphinx>=7.4.7,<8",
+    "Sphinx>=8.0.2",
     "sphinx-book-theme>=1.1.3",
     "sphinx-copybutton>=0.5.2",
     "sphinx_design>=0.6.0",

t_doc_common-0.4/serve.bat

@@ -0,0 +1,5 @@
+@echo off
+rem Copyright 2024 Caroline Blank <caro@c-space.org>
+rem Copyright 2024 Remy Blank <remy@c-space.org>
+rem SPDX-License-Identifier: CC-BY-NC-SA-4.0
+tdoc serve

t_doc_common-0.4/serve.desktop

@@ -0,0 +1,13 @@
+# Copyright 2024 Caroline Blank <caro@c-space.org>
+# Copyright 2024 Remy Blank <remy@c-space.org>
+# SPDX-License-Identifier: CC-BY-NC-SA-4.0
+[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.3.dev1 → t_doc_common-0.4}/tdoc/common/__init__.py

@@ -8,7 +8,8 @@ from docutils import nodes
 from sphinx.directives.code import CodeBlock
 from sphinx.util import logging
 
-__version__ = '0.3.dev1'
+__project__ = 't-doc-common'
+__version__ = '0.4'
 
 _common = pathlib.Path(__file__).absolute().parent
 _root = _common.parent.parent
@@ -23,6 +24,7 @@ _license_urls = {
     'CC-BY-NC-4.0': 'https://creativecommons.org/licenses/by-nc/4.0/',
     'CC-BY-NC-SA-4.0': 'https://creativecommons.org/licenses/by-nc-sa/4.0/',
     'CC-BY-ND-4.0': 'https://creativecommons.org/licenses/by-nd/4.0/',
+    'MIT': 'https://opensource.org/license/mit',
 }
 
 def setup(app):

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

@@ -6,14 +6,18 @@ import argparse
 import contextlib
 from http import server
 import itertools
+from importlib import metadata
+import json
 import pathlib
 import shutil
 import socket
 import stat
 import subprocess
+import sys
 import threading
 import time
 
+from .. import common
 from . import util
 
 
@@ -81,6 +85,10 @@ def main(argv, stdin, stdout, stderr):
     arg('--watch', metavar='PATH', action='append', dest='watch', default=[],
         help="Additional directories to watch for changes.")
 
+    p = subparsers.add_parser('version', add_help=False,
+                              help="Display version information.")
+    p.set_defaults(handler=cmd_version)
+
     cfg = parser.parse_args(argv[1:])
     cfg.stdin, cfg.stdout, cfg.stderr = stdin, stdout, stderr
     cfg.ansi = util.ansi if cfg.color else util.no_ansi
@@ -95,15 +103,6 @@ def cmd_build(cfg):
         if res.returncode != 0: return res.returncode
 
 
-def sphinx_build(cfg, target, *, build, **kwargs):
-    argv = [cfg.sphinx_build, '-M', target, cfg.source, build,
-            '--jobs=auto', '--fail-on-warning']
-    if cfg.debug: argv += ['--show-traceback']
-    argv += cfg.sphinx_opts
-    return subprocess.run(argv, stdin=cfg.stdin, stdout=cfg.stdout,
-                          stderr=cfg.stderr, **kwargs)
-
-
 def cmd_clean(cfg):
     return sphinx_build(cfg, 'clean', build=cfg.build).returncode
 
@@ -129,15 +128,30 @@ def cmd_serve(cfg):
             cfg.stderr.write("Interrupted, exiting\n")
 
 
-class ServerBase(server.ThreadingHTTPServer):
+def cmd_version(cfg):
+    cfg.stdout.write(f"{common.__project__}-{common.__version__}\n")
 
+
+def sphinx_build(cfg, target, *, build, **kwargs):
+    argv = [cfg.sphinx_build, '-M', target, cfg.source, build,
+            '--jobs=auto', '--fail-on-warning']
+    if cfg.debug: argv += ['--show-traceback']
+    argv += cfg.sphinx_opts
+    return subprocess.run(argv, stdin=cfg.stdin, stdout=cfg.stdout,
+                          stderr=cfg.stderr, **kwargs)
+
+
+class ServerBase(server.ThreadingHTTPServer):
     def __init__(self, *args, cfg, **kwargs):
         self.cfg = cfg
         self.lock = threading.Lock()
-        self.directory = self.cfg.build / 'html'
+        self.directory = self.build_dir(0) / 'html'
+        self.upgrade_msg = None
         self.stop = False
         self.builder = threading.Thread(target=self.watch_and_build)
         self.builder.start()
+        self.checker = threading.Thread(target=self.check_upgrade, daemon=True)
+        self.checker.start()
         super().__init__(*args, **kwargs)
 
     def server_bind(self):
@@ -227,10 +241,28 @@ class ServerBase(server.ThreadingHTTPServer):
         if ':' in host: host = f'[{host}]'
         self.cfg.stdout.write(self.cfg.ansi("Serving at <@{LBLUE}%s@{NORM}>\n")
                               % f"http://{host}:{port}/")
+        with self.lock:
+            msg = self.upgrade_msg
+        if msg: self.cfg.stdout.write(msg)
+
+    def check_upgrade(self):
+        try:
+            project = common.__project__
+            upgrades, editable = pip_check_upgrades(self.cfg, project)
+            if project not in upgrades: return
+            msg = self.cfg.ansi(
+                "@{LYELLOW}A t-doc upgrade is available:@{NORM} "
+                "%s @{CYAN}%s@{NORM} => @{CYAN}%s@{NORM}\n"
+                "See <@{LBLUE}https://t-doc.org/common/%s#upgrade@{NORM}>\n"
+                % (project, metadata.version(project), upgrades[project],
+                   'development' if editable else 'install'))
+            with self.lock:
+                self.upgrade_msg = msg
+        except Exception:
+            if self.cfg.debug: raise
 
 
 class HandlerBase(server.SimpleHTTPRequestHandler):
-
     def log_request(self, code='-', size='-'):
         pass
 
@@ -240,5 +272,29 @@ class HandlerBase(server.SimpleHTTPRequestHandler):
             (format % args).translate(self._control_char_table)))
 
 
+class Namespace(dict):
+    def __getattr__(self, name):
+        return self[name]
+
+
+def pip(cfg, *args, json_output=False):
+    p = subprocess.run((sys.executable, '-m', 'pip') + args,
+        stdin=subprocess.DEVNULL, capture_output=True, text=True)
+    if p.returncode != 0: raise Exception(p.stderr)
+    if not json_output: return p.stdout
+    return json.loads(p.stdout, object_pairs_hook=Namespace)
+
+
+def pip_check_upgrades(cfg, package):
+    data = pip(cfg, 'install', '--dry-run', '--upgrade',
+               '--upgrade-strategy=only-if-needed', '--only-binary=:all:',
+               '--report=-', '--quiet', package, json_output=True)
+    upgrades = {pkg.metadata.name: pkg.metadata.version for pkg in data.install}
+    if package not in upgrades: return {}, False
+    pkgs = pip(cfg, 'list', '--editable', '--format=json', json_output=True)
+    editable = any(pkg.name == package for pkg in pkgs)
+    return upgrades, editable
+
+
 if __name__ == '__main__':
     main()

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

@@ -34,13 +34,19 @@ 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
 
 # MyST options.
-myst_enable_extensions = [
+myst_enable_extensions = {
     'amsmath',
+    'attrs_block',
+    'attrs_inline',
     'colon_fence',
     'deflist',
     'dollarmath',
@@ -52,8 +58,9 @@ myst_enable_extensions = [
     'strikethrough',
     'substitution',
     'tasklist',
-]
+}
 myst_dmath_double_inline = True
+myst_heading_anchors = 6
 
 # HTML rendering options.
 html_show_sphinx = False

{t_doc_common-0.3.dev1 → t_doc_common-0.4}/tdoc/common/static/styles/t-doc.css

@@ -6,6 +6,10 @@
     display: none !important;
 }
 
+.line-height-normal .highlight pre {
+    line-height: normal !important;
+}
+
 /* Set the maximum width of sidebars instead of a fixed width. */
 div.sidebar, aside.sidebar {
     max-width: 40%;

t_doc_common-0.3.dev1/.hgtags

@@ -1 +0,0 @@
-267a6c8ad66dde08f2b75d2d82d0d2985ca8f137 0.2

t_doc_common-0.3.dev1/README.md

@@ -1,9 +0,0 @@
-<!-- Copyright 2024 Caroline Blank <caro@c-space.org> -->
-<!-- Copyright 2024 Remy Blank <remy@c-space.org> -->
-<!-- SPDX-License-Identifier: MIT -->
-
-# t-doc - Base commune
-
-Ce package contient la fonctionnalité commune aux documents basés sur t-doc.
-
-Ce logiciel est distribué sous la licence [MIT](LICENSE.txt).