ewokssphinx 2.1.0__py3-none-any.whl

ewokssphinx/__init__.py

@@ -0,0 +1,44 @@
+from pathlib import Path
+
+from sphinx.application import Sphinx
+from sphinx.util.osutil import copyfile
+
+from .ewoks_task_directive import EwoksTaskDirective
+
+
+def setup(app: Sphinx):
+    app.add_directive("ewokstasks", EwoksTaskDirective)
+
+    app.add_config_value(
+        "ewokssphinx_task_cache_path",
+        default=None,
+        types=str,
+        rebuild="env",
+        description="JSON path to cache Ewoks task descriptions. "
+        "Task discovery overrides the cached descriptions. "
+        "Useful when task discovery needs to be done in different python environments.",
+    )
+
+    app.add_config_value(
+        "ewokssphinx_ignore_discovery_error",
+        default=False,
+        types=bool,
+        rebuild="env",
+        description="Ignore Ewoks task discovery errors. ",
+    )
+
+    app.add_css_file("ewokssphinx.css")
+    app.connect("build-finished", _copy_css)
+
+    return {
+        "version": "1.0",
+        "parallel_read_safe": False,  # Reading source files
+        "parallel_write_safe": True,  # Writing output files
+    }
+
+
+def _copy_css(app, exception):
+    if app.builder.name != "html" or exception:
+        return
+    static_dir = Path(app.builder.outdir) / "_static"
+    copyfile(Path(__file__).parent / "ewokssphinx.css", static_dir / "ewokssphinx.css")

ewokssphinx/ewoks_task_directive.py

@@ -0,0 +1,45 @@
+import logging
+
+from docutils.parsers.rst import directives
+from sphinx.util.docutils import SphinxDirective
+
+from .ewoks_task_utils import cached_tasks
+from .ewoks_task_utils import discover_tasks
+from .sphinx_task_utils import task_nodes
+
+logger = logging.getLogger(__name__)
+
+
+def _task_type_option(argument):
+    return directives.choice(argument, ("class", "method", "ppfmethod"))
+
+
+class EwoksTaskDirective(SphinxDirective):
+    required_arguments = 1
+    option_spec = {
+        "task-type": _task_type_option,
+        "ignore-import-error": directives.flag,
+    }
+
+    def run(self):
+        module_pattern = self.arguments[0]
+        task_type = self.options.get("task-type")
+        ignore_import_error = "ignore-import-error" in self.options
+
+        try:
+            local_tasks = discover_tasks(module_pattern, task_type, ignore_import_error)
+        except Exception as ex:
+            if not self.config.ewokssphinx_ignore_discovery_error:
+                raise
+            logger.error(f"Task discovery '{module_pattern}' failed: {ex}")
+            local_tasks = []
+
+        tasks = cached_tasks(
+            local_tasks,
+            self.config.ewokssphinx_task_cache_path,
+            module_pattern,
+            task_type,
+        )
+
+        task_sections = task_nodes(self, tasks)
+        return task_sections

ewokssphinx/ewoks_task_utils.py

@@ -0,0 +1,144 @@
+import importlib
+import inspect
+import json
+from pathlib import Path
+from typing import Any
+
+from ewokscore.task_discovery import discover_tasks_from_modules
+from pydantic import BaseModel
+from pydantic_core import PydanticUndefined
+from sphinx.util.typing import stringify_annotation
+
+from .type_utils import TaskDescription
+
+
+def discover_tasks(
+    module_pattern: str, task_type: str, ignore_import_error: bool
+) -> list[dict[str, Any]]:
+    tasks = []
+    for task in discover_tasks_from_modules(
+        module_pattern,
+        task_type=task_type,
+        raise_import_failure=not ignore_import_error,
+    ):
+        task_name = _get_task_name(task["task_identifier"], task["task_type"])
+
+        if task.get("input_model"):
+            inputs = _parse_pydantic_model(task["input_model"])
+        else:
+            inputs = _parse_parameter_names(
+                task.get("required_input_names", []),
+                task.get("optional_input_names", []),
+            )
+        if task.get("output_model"):
+            outputs = _parse_pydantic_model(task["output_model"])
+        else:
+            outputs = _parse_parameter_names(task.get("output_names", []), [])
+
+        serialized_task = {
+            "task_name": task_name,
+            "task_identifier": task["task_identifier"],
+            "task_type": task["task_type"],
+            "description": _parse_doc(task.get("description")),
+            "inputs": inputs,
+            "outputs": outputs,
+        }
+        _ = TaskDescription(**serialized_task)
+
+        tasks.append(serialized_task)
+    return tasks
+
+
+def cached_tasks(
+    local_tasks: list[dict[str, Any]],
+    json_cache_path: str | Path | None,
+    module_pattern: str,
+    task_type: str,
+) -> list[dict[str, Any]]:
+    """Save tasks in cache or load task from cache when local tasks are empty."""
+    if not json_cache_path:
+        return local_tasks
+
+    json_cache_path = Path(json_cache_path)
+    if json_cache_path.exists():
+        cache = json.loads(json_cache_path.read_text(encoding="utf-8"))
+    else:
+        cache = {}
+
+    module_pattern_dict = cache.setdefault(module_pattern, {})
+    if local_tasks or task_type not in module_pattern_dict:
+        module_pattern_dict[task_type] = local_tasks
+
+    json_cache_path.parent.mkdir(parents=True, exist_ok=True)
+    json_cache_path.write_text(json.dumps(cache, indent=2), encoding="utf-8")
+
+    return module_pattern_dict[task_type]
+
+
+def _get_task_name(identifier: str, task_type: str) -> str:
+    if task_type == "ppfmethod":
+        # ppfmethods are all named `run` so use the module name as task name.
+        return identifier.split(".")[-2]
+    return identifier.split(".")[-1]
+
+
+def _parse_parameter_names(
+    required_names: list[str], optional_names: list[str]
+) -> list[dict[str, str | list[str]]]:
+    parameters = []
+    names = required_names + optional_names
+    is_required = [True] * len(required_names) + [False] * len(optional_names)
+    for name, required in zip(names, is_required):
+        parameter = {
+            "name": name,
+            "annotation": None,
+            "required": required,
+            "description": None,
+            "examples": [],
+            "default": None,
+            "has_default": False,
+        }
+        parameters.append(parameter)
+    return parameters
+
+
+def _parse_pydantic_model(model: BaseModel | None) -> list[dict[str, str | list[str]]]:
+    parameters = []
+    if model is None:
+        return parameters
+
+    model_cls = _import_model(model)
+    for name, field_info in model_cls.model_fields.items():
+        parameters.append(_parse_pydantic_field(name, field_info))
+    return parameters
+
+
+def _import_model(input_model_qual_name: str) -> type:
+    module_name, _, model_name = input_model_qual_name.rpartition(".")
+    mod = importlib.import_module(module_name)
+    return getattr(mod, model_name)
+
+
+def _parse_doc(text) -> str:
+    return inspect.cleandoc(text) if text else ""
+
+
+def _parse_pydantic_field(name, field_info) -> dict[str, str | list[str] | None]:
+    examples = getattr(field_info, "examples", None)
+    default = getattr(field_info, "default", None)
+    if default is PydanticUndefined:
+        default = None
+        has_default = False
+    else:
+        has_default = True
+    examples = [repr(example) for example in examples or []]
+
+    return {
+        "name": name,
+        "annotation": stringify_annotation(field_info.annotation),
+        "required": field_info.is_required(),
+        "description": _parse_doc(field_info.description),
+        "examples": examples,
+        "default": None if default is None else str(default),
+        "has_default": has_default,
+    }

ewokssphinx/ewokssphinx.css

@@ -0,0 +1,16 @@
+.ewokssphinx-task .ewokssphinx-field-list {
+    padding-left: 0.5em;
+}
+
+.ewokssphinx-task .ewokssphinx-default {
+    background-color: transparent;
+    border: none;
+}
+
+.ewokssphinx-task .ewokssphinx-required {
+    color: var(--sd-color-danger, red)
+}
+
+.ewokssphinx-task .ewokssphinx-examples {
+    font-style: italic;
+}

ewokssphinx/sphinx_task_utils.py

@@ -0,0 +1,192 @@
+from typing import Any
+from typing import Sequence
+
+from docutils import nodes
+from sphinx.util.docutils import SphinxDirective
+
+from .type_utils import TaskDescription
+
+
+def task_nodes(
+    directive: SphinxDirective,
+    tasks: Sequence[dict[str, Any]],
+) -> list[nodes.section]:
+    """
+    Convert a list of JSON Ewoks task descriptions into Sphinx/Docutils
+    document node trees.
+
+    Returns a list of <section> nodes.
+    """
+    return [_task_section(directive, task) for task in tasks]
+
+
+def _task_section(directive: SphinxDirective, task: dict[str, Any]) -> nodes.section:
+    _ = TaskDescription(**task)
+
+    section = nodes.section(
+        "",
+        ids=[task["task_identifier"]],
+        classes=["ewokssphinx-task"],
+    )
+
+    # Title
+    section.append(nodes.title(text=task["task_name"]))
+
+    # Description
+    if task["description"]:
+        section.extend(_rst_to_nodes(directive, task["description"]))
+
+    # Identifier + task type
+    section.append(
+        nodes.field_list(
+            "",
+            _field_node("Identifier", nodes.literal(text=task["task_identifier"])),
+            _field_node("Task type", nodes.Text(task["task_type"])),
+        )
+    )
+
+    # Combine inputs + outputs in a container so that
+    # Sphinx does not attach the "simple" CSS class.
+    io_def = nodes.container("")
+    if task["inputs"]:
+        input_parameters = _parameter_nodes(
+            directive,
+            title="Inputs:",
+            css_classes=["field-odd"],
+            parameters=task["inputs"],
+            is_outputs=False,
+        )
+        io_def.append(input_parameters)
+
+    if task["outputs"]:
+        output_parameters = _parameter_nodes(
+            directive,
+            title="Outputs:",
+            css_classes=["field-even"],
+            parameters=task["outputs"],
+            is_outputs=True,
+        )
+        io_def.append(output_parameters)
+
+    section.append(
+        nodes.definition_list(
+            "",
+            io_def,
+            classes=["ewokssphinx-field-list"],
+        )
+    )
+
+    return section
+
+
+def _field_node(name: str, body: nodes.Element) -> nodes.field:
+    """Construct a Sphinx field like:  Identifier: my.module.Task"""
+    return nodes.field(
+        "",
+        nodes.field_name(text=name),
+        nodes.field_body("", body),
+    )
+
+
+def _term_node(name: str, is_required: bool) -> nodes.term:
+    """
+    Create a term:
+
+        my_input
+        my_input*
+    """
+    if not is_required:
+        return nodes.term(text=name)
+
+    # Required input -> add "*"
+    return nodes.term(
+        "",
+        name,
+        nodes.strong("", "*", classes=["ewokssphinx-required"]),
+    )
+
+
+def _parameter_nodes(
+    directive: SphinxDirective,
+    title: str,
+    css_classes: list[str],
+    parameters: dict[str, str | list[str] | None],
+    is_outputs: bool,
+) -> nodes.definition_list_item:
+
+    dl = nodes.definition_list()
+    for parameter in parameters:
+        dl.append(_parameter_node(directive, parameter, is_outputs))
+
+    return nodes.definition_list_item(
+        "",
+        nodes.term(text=title, classes=css_classes),
+        nodes.definition("", dl),
+        classes=["field-list"],
+    )
+
+
+def _parameter_node(
+    directive: SphinxDirective, parameter: dict[str, Any], is_output: bool
+) -> nodes.definition_list_item:
+    """
+    Full parameter description structure:
+
+        name* : annotation = default
+        Description...
+
+        Examples:
+            'foo'
+            'bar'
+    """
+
+    # Build the term
+    #
+    #   name* : annotation = default
+    #
+    is_required = parameter["required"] and not is_output
+    term = _term_node(parameter["name"], is_required)
+
+    if parameter["annotation"]:
+        term.extend([nodes.Text(" : "), nodes.literal(text=parameter["annotation"])])
+
+    has_default = (
+        parameter["has_default"] and not parameter["required"] and not is_output
+    )
+    if has_default:
+        term.append(
+            nodes.literal(
+                text=f"= {parameter['default']}",
+                classes=["ewokssphinx-default"],
+            )
+        )
+
+    # Description
+    definition = nodes.definition()
+    if parameter["description"]:
+        definition.extend(_rst_to_nodes(directive, parameter["description"]))
+
+    # Examples
+    examples = parameter.get("examples")
+    if examples:
+        definition.append(_examples_node(examples))
+
+    return nodes.definition_list_item("", term, definition)
+
+
+def _examples_node(examples: list[Any]) -> nodes.container:
+    bl = nodes.bullet_list()
+    for example in examples:
+        bl.append(nodes.list_item("", nodes.Text(example)))
+
+    return nodes.container(
+        "",
+        nodes.Text("Examples:"),
+        bl,
+        classes=["ewokssphinx-examples"],
+    )
+
+
+def _rst_to_nodes(directive: SphinxDirective, text: str) -> list[nodes.Node]:
+    # TODO: directives like ".. note::" still appear as plain text.
+    return directive.parse_text_to_nodes(text)

ewokssphinx/tests/conftest.py

@@ -0,0 +1,109 @@
+import json
+
+import pytest
+from sphinx.testing.util import SphinxTestApp
+
+
+@pytest.fixture(scope="session")
+def app(tmp_path_factory):
+    srcdir = tmp_path_factory.mktemp("app")
+    with open(srcdir / "conf.py", "w") as conf:
+        conf.write('extensions = ["ewokssphinx"]')
+    app = SphinxTestApp(
+        "html", srcdir=srcdir, docutils_conf="[readers]\ndocinfo_xform: no"
+    )
+
+    return app
+
+
+@pytest.fixture(scope="session")
+def app_with_cache(tmp_path_factory):
+    srcdir = tmp_path_factory.mktemp("app_with_cache")
+    json_cache_path = srcdir / "discovered_ewoks_tasks.json"
+    with open(srcdir / "conf.py", "w") as conf:
+        conf.write('extensions = ["ewokssphinx"]\n')
+        conf.write(f'ewokssphinx_task_cache_path = "{json_cache_path.as_posix()}"\n')
+        conf.write("ewokssphinx_ignore_discovery_error = True\n")
+
+    task = {
+        "task_name": "MyNonExistingTask",
+        "task_identifier": "ewoksnoexisting.tasks.MyNonExistingTask",
+        "task_type": "class",
+        "description": "My non-existing task documentation",
+        "inputs": [
+            {
+                "annotation": None,
+                "default": None,
+                "description": None,
+                "examples": [],
+                "has_default": False,
+                "name": "a",
+                "required": True,
+            },
+            {
+                "annotation": None,
+                "default": None,
+                "description": None,
+                "examples": [],
+                "has_default": False,
+                "name": "b",
+                "required": True,
+            },
+            {
+                "annotation": None,
+                "default": None,
+                "description": None,
+                "examples": [],
+                "has_default": False,
+                "name": "c",
+                "required": True,
+            },
+            {
+                "annotation": None,
+                "default": None,
+                "description": None,
+                "examples": [],
+                "has_default": False,
+                "name": "d",
+                "required": False,
+            },
+            {
+                "annotation": None,
+                "default": None,
+                "description": None,
+                "examples": [],
+                "has_default": False,
+                "name": "e",
+                "required": False,
+            },
+        ],
+        "outputs": [
+            {
+                "annotation": None,
+                "default": None,
+                "description": None,
+                "examples": [],
+                "has_default": False,
+                "name": "error",
+                "required": True,
+            },
+            {
+                "annotation": None,
+                "default": None,
+                "description": None,
+                "examples": [],
+                "has_default": False,
+                "name": "result",
+                "required": True,
+            },
+        ],
+    }
+    cache = {"ewoksnoexisting.tasks.MyNonExistingTask": {"class": [task]}}
+    with open(json_cache_path, "w") as fp:
+        json.dump(cache, fp)
+
+    app = SphinxTestApp(
+        "html", srcdir=srcdir, docutils_conf="[readers]\ndocinfo_xform: no"
+    )
+
+    return app

ewokssphinx/tests/dummy_tasks.py

@@ -0,0 +1,33 @@
+from ewokscore import Task
+
+
+class MyTask(
+    Task,
+    input_names=["a", "b", "c"],
+    optional_input_names=["d", "e"],
+    output_names=["result", "error"],
+):
+    """My task documentation"""
+
+    def run(self):
+        pass
+
+
+def my_other_task(f, g, h=None):
+    pass
+
+
+def run(i, j=None, k=None):
+    """Run task documentation"""
+
+    pass
+
+
+class _HiddenTask(
+    Task,
+    input_names=["one"],
+    optional_input_names=["two", "three"],
+    output_names=["result", "error"],
+):
+    def run(self):
+        pass

ewokssphinx/tests/dummy_tasks_pydantic.py

@@ -0,0 +1,30 @@
+from ewokscore import Task
+from ewokscore.model import BaseInputModel
+from ewokscore.model import BaseOutputModel
+from pydantic import Field
+
+
+class Inputs(BaseInputModel):
+    planet: str = "Earth"
+    latitude: int = Field(examples=[-90, 0, 90])
+    longitude: float = Field(
+        description="Longitude of the GPS point. **In degrees.**", examples=[-90, 0, 90]
+    )
+
+
+class Outputs(BaseOutputModel):
+    location: str = Field(
+        ..., description="Name of the closest city or location to the given coordinates"
+    )
+    error: Exception | None
+
+
+class FindLocation(
+    Task,
+    input_model=Inputs,
+    output_model=Outputs,
+):
+    """Finds a location given the GPS coordinates"""
+
+    def run(self):
+        pass

ewokssphinx/tests/test_task_cache.py

@@ -0,0 +1,26 @@
+from sphinx.testing import restructuredtext
+
+from .test_utils import assert_task_nodes
+
+
+def test_cache(app_with_cache):
+    parsed_nodes = restructuredtext.parse(
+        app_with_cache,
+        """.. ewokstasks:: ewoksnoexisting.tasks.MyNonExistingTask
+              :task-type: class
+        """,
+    )
+    assert len(parsed_nodes) == 4
+    _assert_class_task_nodes(parsed_nodes)
+
+
+def _assert_class_task_nodes(nodes):
+    assert_task_nodes(
+        nodes,
+        identifier="ewoksnoexisting.tasks.MyNonExistingTask",
+        doc="""My non-existing task documentation""",
+        task_type="class",
+        required_inputs=["a", "b", "c"],
+        optional_inputs=["d", "e"],
+        outputs=["error", "result"],
+    )

ewokssphinx/tests/test_task_directive.py

@@ -0,0 +1,117 @@
+import pytest
+from sphinx.testing import restructuredtext
+
+from .test_utils import assert_task_nodes
+
+
+def test_ewokstasks(app):
+    parsed_nodes = restructuredtext.parse(
+        app, ".. ewokstasks:: ewokssphinx.tests.dummy_tasks"
+    )
+
+    assert len(parsed_nodes) == 4
+    _assert_class_task_nodes(parsed_nodes[0])
+    _assert_ppfmethod_nodes(parsed_nodes[1])
+    _assert_method_nodes(parsed_nodes[2:])
+
+
+def test_ewokstasks_class(app):
+    parsed_nodes = restructuredtext.parse(
+        app,
+        """.. ewokstasks:: ewokssphinx.tests.dummy_tasks
+              :task-type: class
+        """,
+    )
+
+    assert len(parsed_nodes) == 4
+    _assert_class_task_nodes(parsed_nodes)
+
+
+def test_ewokstasks_method(app):
+    parsed_nodes = restructuredtext.parse(
+        app,
+        """.. ewokstasks:: ewokssphinx.tests.dummy_tasks
+              :task-type: method
+        """,
+    )
+
+    assert len(parsed_nodes) == 2
+    _assert_method_nodes(parsed_nodes)
+
+
+def test_ewokstasks_ppfmethod(app):
+    parsed_nodes = restructuredtext.parse(
+        app,
+        """.. ewokstasks:: ewokssphinx.tests.dummy_tasks
+              :task-type: ppfmethod
+        """,
+    )
+
+    assert len(parsed_nodes) == 4
+    _assert_ppfmethod_nodes(parsed_nodes)
+
+
+def test_ewokstasks_raised_import_error(app):
+    with pytest.raises(ImportError):
+        restructuredtext.parse(
+            app,
+            """.. ewokstasks:: not_existing
+            """,
+        )
+
+
+def test_ewokstasks_ignore_import_error(app):
+    parsed_nodes = restructuredtext.parse(
+        app,
+        """.. ewokstasks:: not_existing
+            :ignore-import-error:
+        """,
+    )
+
+    assert len(parsed_nodes) == 0
+
+
+def _assert_class_task_nodes(nodes):
+    assert_task_nodes(
+        nodes,
+        identifier="ewokssphinx.tests.dummy_tasks.MyTask",
+        doc="""My task documentation""",
+        task_type="class",
+        required_inputs=["a", "b", "c"],
+        optional_inputs=["d", "e"],
+        outputs=["error", "result"],
+    )
+
+
+def _assert_method_nodes(nodes):
+    assert_task_nodes(
+        nodes[0],
+        identifier="ewokssphinx.tests.dummy_tasks.my_other_task",
+        doc=None,
+        task_type="method",
+        required_inputs=["f", "g"],
+        optional_inputs=["h"],
+        outputs=["return_value"],
+    )
+
+    assert_task_nodes(
+        nodes[1],
+        identifier="ewokssphinx.tests.dummy_tasks.run",
+        doc="""Run task documentation""",
+        task_type="method",
+        required_inputs=["i"],
+        optional_inputs=["j", "k"],
+        outputs=["return_value"],
+    )
+
+
+def _assert_ppfmethod_nodes(nodes):
+    assert_task_nodes(
+        nodes,
+        identifier="ewokssphinx.tests.dummy_tasks.run",
+        doc="""Run task documentation""",
+        task_type="ppfmethod",
+        required_inputs=["i"],
+        optional_inputs=["j", "k"],
+        outputs=["return_value"],
+    )

ewokssphinx/tests/test_task_directive_pydantic.py

@@ -0,0 +1,59 @@
+from docutils import nodes
+from sphinx.testing import restructuredtext
+
+from .test_utils import assert_node
+from .test_utils import assert_task_preamble
+
+
+def test_ewokstasks_with_pydantic_input_model(app):
+    parsed_nodes = restructuredtext.parse(
+        app,
+        """.. ewokstasks:: ewokssphinx.tests.dummy_tasks_pydantic
+              :task-type: class
+        """,
+    )
+
+    assert len(parsed_nodes) == 4
+    assert_task_preamble(
+        parsed_nodes,
+        "ewokssphinx.tests.dummy_tasks_pydantic.FindLocation",
+        """Finds a location given the GPS coordinates""",
+        "class",
+    )
+    definition_list_node = parsed_nodes[-1]
+    container_node = definition_list_node[0]
+
+    input_list = container_node[0]
+    input_term, input_definition = input_list
+    assert_node(input_term, nodes.term, "Inputs:")
+    assert_node(input_definition, nodes.definition)
+
+    assert_node(input_definition[0][0][0], nodes.term, "planet : str= Earth")
+    assert_node(input_definition[0][1][0], nodes.term, "latitude* : int")
+    assert_node(input_definition[0][2][0], nodes.term, "longitude* : float")
+
+    longitude_definition = input_definition[0][2][1]
+    longitude_description, longitude_examples = longitude_definition
+    longitude_examples_title, longitude_examples = longitude_examples
+    assert_node(longitude_description, nodes.paragraph)
+    assert_node(longitude_description[0], nodes.Text, "Longitude of the GPS point. ")
+    assert_node(longitude_description[1], nodes.strong, "In degrees.")
+    assert_node(longitude_examples_title, nodes.Text, "Examples:")
+    for longitude_example, value in zip(longitude_examples, [-90, 0, 90]):
+        assert_node(longitude_example[0], nodes.Text, repr(value))
+
+    output_list = container_node[1]
+    output_term, output_definition = output_list
+    assert_node(output_term, nodes.term, "Outputs:")
+    assert_node(output_definition, nodes.definition)
+
+    assert_node(output_definition[0][0][0], nodes.term, "location : str")
+    assert_node(output_definition[0][1][0], nodes.term, "error : Exception | None")
+
+    location_definition = output_definition[0][0][1]
+    (location_definition,) = location_definition
+    assert_node(
+        location_definition[0],
+        nodes.Text,
+        "Name of the closest city or location to the given coordinates",
+    )

ewokssphinx/tests/test_utils.py

@@ -0,0 +1,71 @@
+from typing import Type
+
+from docutils import nodes
+from docutils.nodes import Node
+
+from ..ewoks_task_utils import _get_task_name
+
+
+def assert_node(node, cls: Type[Node], text: str | None = None):
+    assert isinstance(node, cls)
+    if text is not None:
+        assert node.astext() == text
+
+
+def assert_field_node(node, name: str, value: str):
+    assert isinstance(node, nodes.field)
+    assert_node(node[0], nodes.field_name, name)
+    assert_node(node[1], nodes.field_body, value)
+
+
+def assert_simple_inputs(input_list, required_inputs, optional_inputs):
+    input_term, input_definition = input_list
+    assert_node(input_term, nodes.term, "Inputs:")
+    assert_node(input_definition, nodes.definition)
+
+    n_required = len(required_inputs)
+    for i in range(n_required):
+        assert_node(input_definition[0][i][0], nodes.term, f"{required_inputs[i]}*")
+
+    n_optional = len(optional_inputs)
+    for i in range(n_optional):
+        assert_node(
+            input_definition[0][n_required + i][0], nodes.term, optional_inputs[i]
+        )
+
+
+def assert_simple_outputs(output_list, outputs):
+    output_term, output_definition = output_list
+    assert_node(output_term, nodes.term, "Outputs:")
+    assert_node(output_definition, nodes.definition)
+    for i, output_name in enumerate(outputs):
+        assert_node(output_definition[0][i][0], nodes.term, output_name)
+
+
+def assert_task_nodes(
+    parsed_nodes, identifier, doc, task_type, required_inputs, optional_inputs, outputs
+):
+    assert_task_preamble(parsed_nodes, identifier, doc, task_type)
+    definition_list_node = parsed_nodes[-1]
+    container_node = definition_list_node[0]
+    input_list = container_node[0]
+    assert_simple_inputs(
+        input_list,
+        required_inputs=required_inputs,
+        optional_inputs=optional_inputs,
+    )
+    output_list = container_node[1]
+    assert_simple_outputs(output_list, outputs=outputs)
+
+
+def assert_task_preamble(parsed_nodes, identifier, doc, task_type):
+    name = _get_task_name(identifier, task_type)
+    assert_node(parsed_nodes[0], nodes.title, name)
+    if doc is not None:
+        assert_node(parsed_nodes[1], nodes.paragraph, doc)
+        field_list_nodes = parsed_nodes[2]
+    else:
+        field_list_nodes = parsed_nodes[1]
+    assert_node(field_list_nodes, nodes.field_list)
+    assert_field_node(field_list_nodes[0], name="Identifier", value=identifier)
+    assert_field_node(field_list_nodes[1], name="Task type", value=task_type)

ewokssphinx/type_utils.py

@@ -0,0 +1,20 @@
+from pydantic import BaseModel
+
+
+class TaskParameter(BaseModel, extra="forbid"):
+    name: str
+    annotation: str | None
+    required: bool
+    description: str | None
+    examples: list[str]
+    default: str | None
+    has_default: bool
+
+
+class TaskDescription(BaseModel, extra="forbid"):
+    task_name: str
+    task_identifier: str
+    task_type: str
+    description: str
+    inputs: list[TaskParameter]
+    outputs: list[TaskParameter]

ewokssphinx-2.1.0.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: ewokssphinx
+Version: 2.1.0
+Summary: Ewoks Sphinx directives
+Author-email: ESRF <dau-pydev@esrf.fr>
+License: # MIT License
+        
+        **Copyright (c) 2026 European Synchrotron Radiation Facility**
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy of
+        this software and associated documentation files (the "Software"), to deal in
+        the Software without restriction, including without limitation the rights to
+        use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+        the Software, and to permit persons to whom the Software is furnished to do so,
+        subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+        FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+        COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+        IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+        CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/ewoks-kit/ewokssphinx/
+Project-URL: Documentation, https://github.com/ewoks-kit/ewokssphinx/blob/main/README.md
+Project-URL: Repository, https://github.com/ewoks-kit/ewokssphinx/
+Project-URL: Issues, https://github.com/ewoks-kit/ewokssphinx/issues
+Project-URL: Changelog, https://github.com/ewoks-kit/ewokssphinx/blob/main/CHANGELOG.md
+Keywords: ewoks,sphinx
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: Sphinx :: Extension
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: sphinx
+Requires-Dist: ewokscore>=3.1.0
+Requires-Dist: pydantic
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Provides-Extra: dev
+Requires-Dist: ewokssphinx[test]; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: doc
+Requires-Dist: ewokssphinx[test]; extra == "doc"
+Requires-Dist: myst-parser; extra == "doc"
+Requires-Dist: pydata_sphinx_theme; extra == "doc"
+Requires-Dist: sphinx-design; extra == "doc"
+Dynamic: license-file
+
+# ewokssphinx
+
+
+[![Pipeline](https://github.com/ewoks-kit/ewokssphinx/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/ewoks-kit/ewokssphinx/actions/workflows/test.yml)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![License](https://img.shields.io/github/license/ewoks-kit/ewokssphinx)](https://github.com/ewoks-kit/ewokssphinx/blob/main/LICENSE.md)
+[![Coverage](https://codecov.io/gh/ewoks-kit/ewokssphinx/branch/main/graph/badge.svg)](https://codecov.io/gh/ewoks-kit/ewokssphinx)
+[![Docs](https://readthedocs.org/projects/ewokssphinx/badge/?version=latest)](https://ewokssphinx.readthedocs.io/en/latest/?badge=latest)
+[![PyPI](https://img.shields.io/pypi/v/ewokssphinx)](https://pypi.org/project/ewokssphinx/)
+
+A set of Sphinx directives for Ewoks
+
+## Quick start
+
+```bash
+pip install ewokssphinx
+```
+
+Then, add `ewokssphinx` to the list of `extensions` in the Sphinx configuration file:
+
+```python
+# conf.py
+
+...
+
+extensions = [
+    ...,
+    "ewokssphinx"
+]
+```
+
+## Documentation
+
+[Full documentation](https://ewokssphinx.readthedocs.io/en/latest) with [examples](https://ewokssphinx.readthedocs.io/en/latest/examples.html)

ewokssphinx-2.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+ewokssphinx/__init__.py,sha256=PBgd9wyQEh2NyHaB9fD9lyYH7Nlk_0pPfMqOPjimayU,1290
+ewokssphinx/ewoks_task_directive.py,sha256=Fs1nAvCbgeC7N1LBCycSzBYhlxa9swDlf9M4R2W8Mxg,1330
+ewokssphinx/ewoks_task_utils.py,sha256=xyKDU-LicWt-xKEw4W52i_BTiFk5k80UdfYAIcYwfcs,4656
+ewokssphinx/ewokssphinx.css,sha256=_K6rcN2skZOrG535NmmbB6Mgo9KZmR_vn11il-Qj9Rc,321
+ewokssphinx/sphinx_task_utils.py,sha256=_yCrxP-8gSXYcLUB4gxW9nRfLZnJVhTpA5t0bWQ356k,4948
+ewokssphinx/type_utils.py,sha256=tZ5mjikkaf9SS_epEO1r8-hVu2jrMMNHKk1ri1pcSBw,440
+ewokssphinx/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ewokssphinx/tests/conftest.py,sha256=oFJKQ5X0WYsPbrPUkLA4zzs-urlDblF_7MG4BeqGK-c,3287
+ewokssphinx/tests/dummy_tasks.py,sha256=AzOcfyVJXyiHiv9oRg6dqD8iHftkUXaK67ty3cID4SY,518
+ewokssphinx/tests/dummy_tasks_pydantic.py,sha256=du6r2zpdApNr36IbrRQPyYUqqsyvkDj-sfOa4fVaZTM,728
+ewokssphinx/tests/test_task_cache.py,sha256=pIGra8-BxBusjpmtupEZrLnfZgCt5GjRIM5tK0_YVlo,723
+ewokssphinx/tests/test_task_directive.py,sha256=V06dfDW-1Dx0Jw5dIXn2SBmPtyP9xzdzKWJUoSQQvuM,2884
+ewokssphinx/tests/test_task_directive_pydantic.py,sha256=Jie1yE0Nhdo2kLRzsBpEmyIzYGbyokh1MakvVTerxMM,2328
+ewokssphinx/tests/test_utils.py,sha256=HzU5vr2ENZ5_2TJA8-eJ5yeLb-PNJ6avFdKo_fvyruI,2469
+ewokssphinx-2.1.0.dist-info/licenses/LICENSE.md,sha256=jhnnemwVcGW_Dc_FbaaD12x2Vz9mIqjX_MtyKrjw3gQ,1102
+ewokssphinx-2.1.0.dist-info/METADATA,sha256=aLlPLLMUYuSY5-vxARrSy7EDXQttd7-PVdgd0m08IJg,3777
+ewokssphinx-2.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ewokssphinx-2.1.0.dist-info/top_level.txt,sha256=uj9wRIAtZZM_KtQWHn9rhn5tfZraEGwqMuNeDeV9AWY,12
+ewokssphinx-2.1.0.dist-info/RECORD,,

ewokssphinx-2.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ewokssphinx-2.1.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,20 @@
+# MIT License
+
+**Copyright (c) 2026 European Synchrotron Radiation Facility**
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

ewokssphinx-2.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ewokssphinx