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

t_doc_common-0.4.dev1/.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.3.dev1 → t_doc_common-0.4.dev1}/.hgtags

@@ -1 +1,2 @@
 267a6c8ad66dde08f2b75d2d82d0d2985ca8f137 0.2
+ea2973414a3779c7ffbed73279ab8d811c795268 0.3

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

@@ -1,8 +1,9 @@
 Metadata-Version: 2.3
 Name: t-doc-common
-Version: 0.3.dev1
+Version: 0.4.dev1
 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.dev1/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.dev1/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.dev1/docs/development.md

@@ -0,0 +1,48 @@
+<!-- Copyright 2024 Caroline Blank <caro@c-space.org> -->
+<!-- Copyright 2024 Remy Blank <remy@c-space.org> -->
+<!-- SPDX-License-Identifier: MIT -->
+
+# Development
+
+## 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.
+  ```{code-block} shell-session
+  python -m pip install --user --editable .
+  ```
+
+## 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.
+  ```{code-block} shell-session
+  python -m pip install --user --upgrade --editable .
+  ```

t_doc_common-0.4.dev1/docs/index.md

@@ -0,0 +1,14 @@
+<!-- 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
+development
+```

t_doc_common-0.4.dev1/docs/install.md

@@ -0,0 +1,65 @@
+<!-- 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
+  ```
+
+  ```{admonition} TODO
+  TODO: Describe how to update .hgrc to configure the name and email address.
+  ```
+
+- (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
+
+- 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.
+  ```{code-block} shell-session
+  python -m pip install --user t-doc-common
+  ```
+
+## Upgrade
+
+- Upgrade the `t-doc-common` package and any out-of-date dependencies.
+  ```{code-block} shell-session
+  python -m pip install --user --upgrade t-doc-common
+  ```

{t_doc_common-0.3.dev1 → t_doc_common-0.4.dev1}/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.3.dev1 → t_doc_common-0.4.dev1}/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.dev1'
 
 _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.dev1}/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.dev1}/tdoc/common/defaults.py

@@ -39,7 +39,7 @@ graphviz_output_format = 'svg'
 todo_include_todos = True
 
 # MyST options.
-myst_enable_extensions = [
+myst_enable_extensions = {
     'amsmath',
     'colon_fence',
     'deflist',
@@ -52,8 +52,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/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).