Override generated code
=======================

The build step emits ``_generated/`` files mechanically from
``library.json`` and ``semantics.json``. Some H5P libraries have
structural shapes the semantics walk cannot express correctly:
deeply nested structural children, cross-library references, or
directive options whose validation needs behaviour beyond the
generated validators.

The package layout accommodates this without forking the generator.
Alongside ``_generated/``, hand-written modules act as overrides.

Pattern
-------

Each generated module has a hand-written counterpart with the same
public ``register(app)`` entry point:

+-------------------------------+-------------------------------+
| Generated                     | Manual override               |
+===============================+===============================+
| ``_generated/directive.py``   | ``directives.py``             |
+-------------------------------+-------------------------------+
| ``_generated/__init__.py``    | (never overridden; assets are |
| (asset registration)          | always generated)             |
+-------------------------------+-------------------------------+

The package's ``__init__.py``, itself generated from the bootstrap
template, loads the manual module first and falls back to the
generated one::

    try:
        from . import directives
        directives.register(app)
    except ImportError:
        try:
            from ._generated import directive
            directive.register(app)
        except ImportError:
            pass

Adding an override therefore is additive: the generated module keeps
existing, future ``make build`` runs keep regenerating it, and the
manual module silently takes over at runtime.

When to override
----------------

- The generated directive does not correctly parse structural
  children that the content type accepts.
- A content type's ``semantics.json`` encodes validation that cannot
  be expressed by the generator's ``select``/``text``/``flag``
  validator set.
- A content type needs doctree nodes or transforms beyond what the
  generator emits (e.g. a visitor that post-processes children).

Practical steps
---------------

1. Run ``make build`` first, to have a concrete reference in
   ``_generated/directive.py``.
2. Copy the file to ``src/byteb4rb1e/sphinxcontrib/h5p/<dir_name>/directives.py``.
3. Adjust the copied module; keep the ``register(app)`` entry point
   and the directive/node class names so downstream RST stays
   source-compatible.
4. Do not edit ``_generated/``; those edits are lost on the next
   build.

Verifying the override wins
---------------------------

After the override is in place, import the package and check which
module it picked up::

    import byteb4rb1e.sphinxcontrib.h5p.<dir_name> as pkg
    import byteb4rb1e.sphinxcontrib.h5p.<dir_name>.directives as m
    print(m.__file__)

If the path ends in ``directives.py`` (not ``_generated/directive.py``),
the override is active.
