Understanding directive content translations.

.gitignore

@@ -0,0 +1,5 @@
+build/
+.venv/
+.envrc
+__pycache__/
+*.mo

Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

README.md

@@ -0,0 +1,34 @@
+# Update pot file
+
+    make gettext
+
+
+# Update po file from pot file
+
+    msgmerge --update locale/fr/LC_MESSAGES/index.po build/gettext/index.pot
+
+
+# Build in english
+
+    make html
+
+
+# Build in french
+
+    make html SPHINXOPTS="-D locale_dirs=$(pwd)/locale -D language=fr"
+
+
+# In english it yields
+
+> availability
+
+> Availability: Unix, not Emscripten, not WASI.
+
+> Hello world I’m the content of the “availability” directive.
+
+
+# While in French the content of the directive is lost
+
+> disponibilité
+
+> Disponibilité: Unix, mais pas Emscripten, ni WASI.

locale/fr/LC_MESSAGES/index.po

@@ -0,0 +1,30 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2023, mdk
+# This file is distributed under the same license as the availability package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: availability \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2023-02-08 15:42+0100\n"
+"PO-Revision-Date: 2023-02-08 15:44+0100\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Langauge: fr\n"
+
+#: ../../source/index.rst:7
+msgid "availability"
+msgstr "disponibilité"
+
+#: ../../source/index.rst:-1
+msgid ":ref:`Availability <availability>`: Unix, not Emscripten, not WASI."
+msgstr ""
+":ref:`Disponibilité <availability>`: Unix, mais pas Emscripten, ni WASI."
+
+#: ../../source/index.rst:11
+msgid "Hello world I'm the content of the \"availability\" directive."
+msgstr "Coucou les gens je suis le contenu de la directive \"disponibilité\"."

source/conf.py

@@ -0,0 +1,32 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+import sys
+import os
+
+project = 'availability'
+copyright = '2023, mdk'
+author = 'mdk'
+
+sys.path.append(os.path.abspath('.'))
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ["pyspecific"]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+html_static_path = ['_static']

source/index.rst

@@ -0,0 +1,13 @@
+.. availability documentation master file, created by
+   sphinx-quickstart on Wed Feb  8 13:30:04 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+.. _availability:
+
+availability
+============
+
+.. availability:: Unix, not Emscripten, not WASI.
+
+   Hello world I'm the content of the "availability" directive.

source/pyspecific.py

@@ -0,0 +1,77 @@
+from docutils.parsers.rst import Directive
+from docutils import nodes
+
+
+class Availability(Directive):
+
+    has_content = True
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+
+    # known platform, libc, and threading implementations
+    known_platforms = frozenset({
+        "AIX", "Android", "BSD", "DragonFlyBSD", "Emscripten", "FreeBSD",
+        "Linux", "NetBSD", "OpenBSD", "POSIX", "Solaris", "Unix", "VxWorks",
+        "WASI", "Windows", "macOS",
+        # libc
+        "BSD libc", "glibc", "musl",
+        # POSIX platforms with pthreads
+        "pthreads",
+    })
+
+    def run(self):
+        availability_ref = ':ref:`Availability <availability>`: '
+        pnode = nodes.paragraph(availability_ref + self.arguments[0],
+                                classes=["availability"],)
+        n, m = self.state.inline_text(availability_ref, self.lineno)
+        pnode.extend(n + m)
+        n, m = self.state.inline_text(self.arguments[0], self.lineno)
+        pnode.extend(n + m)
+        if self.content:
+            self.state.nested_parse(self.content, self.content_offset, pnode)
+
+        self.parse_platforms()
+
+        return [pnode]
+
+    def parse_platforms(self):
+        """Parse platform information from arguments
+
+        Arguments is a comma-separated string of platforms. A platform may
+        be prefixed with "not " to indicate that a feature is not available.
+
+        Example::
+
+           .. availability:: Windows, Linux >= 4.2, not Emscripten, not WASI
+
+        Arguments like "Linux >= 3.17 with glibc >= 2.27" are currently not
+        parsed into separate tokens.
+        """
+        platforms = {}
+        for arg in self.arguments[0].rstrip(".").split(","):
+            arg = arg.strip()
+            platform, _, version = arg.partition(" >= ")
+            if platform.startswith("not "):
+                version = False
+                platform = platform[4:]
+            elif not version:
+                version = True
+            platforms[platform] = version
+
+        unknown = set(platforms).difference(self.known_platforms)
+        if unknown:
+            cls = type(self)
+            logger = logging.getLogger(cls.__qualname__)
+            logger.warn(
+                f"Unknown platform(s) or syntax '{' '.join(sorted(unknown))}' "
+                f"in '.. availability:: {self.arguments[0]}', see "
+                f"{__file__}:{cls.__qualname__}.known_platforms for a set "
+                "known platforms."
+            )
+
+        return platforms
+
+def setup(app):
+    app.add_directive('availability', Availability)
+    return {'version': '1.0', 'parallel_read_safe': True}