commit be32b5740713a2bf16349ecd9d05e59dc5f72bf7 Author: Julien Palard Date: Wed Feb 8 15:49:42 2023 +0100 Understanding directive content translations. diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..79c3d66 --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +build/ +.venv/ +.envrc +__pycache__/ +*.mo diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/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) diff --git a/README.md b/README.md new file mode 100644 index 0000000..6314f88 --- /dev/null +++ b/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. diff --git a/locale/fr/LC_MESSAGES/index.po b/locale/fr/LC_MESSAGES/index.po new file mode 100644 index 0000000..7bf38c1 --- /dev/null +++ b/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 , 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 \n" +"Language-Team: LANGUAGE \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 `: Unix, not Emscripten, not WASI." +msgstr "" +":ref:`Disponibilité `: 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é\"." diff --git a/source/conf.py b/source/conf.py new file mode 100644 index 0000000..d4c3077 --- /dev/null +++ b/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'] diff --git a/source/index.rst b/source/index.rst new file mode 100644 index 0000000..af47a24 --- /dev/null +++ b/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. diff --git a/source/pyspecific.py b/source/pyspecific.py new file mode 100644 index 0000000..c590487 --- /dev/null +++ b/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 `: ' + 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}