Add a new content type
======================

This walkthrough adds a new H5P content type to the monorepo
end-to-end, from vendor repo to installable Sphinx extension.

1. Register the vendor repository
---------------------------------

If the content type is already in the public H5P catalogue, re-run
the mirror and the index::

    make mirror-sync
    make index

The new entry appears in ``data/package-index.json`` keyed by its
``machine_name`` (for example ``H5P.TrueFalse``).

If the content type is not in the public catalogue, add its source
repo to the mirror manually, then proceed as above.

2. Scaffold the Python package
------------------------------

From the monorepo root::

    python3 -m byteb4rb1e.sphinxcontrib.h5p.utils.pkg bootstrap \
        H5P.TrueFalse

The run expands the request to include the full
``preloadedDependencies`` closure, so every H5P library reached by
the requested content type is scaffolded in the same pass. A
subsequent editable install of any one package resolves all its
siblings from local paths.

The new directory tree lives at ``<dir_name>/`` (see the README's
naming taxonomy for what ``dir_name`` resolves to). Inside, a
``pyproject.toml``, a vendor submodule under ``vendor/``, and a
minimal ``__init__.py`` are ready to consume the next stage.

3. Generate package specifics
-----------------------------

Change into the new package directory and run::

    make build

This reads the vendored ``library.json`` and ``semantics.json`` and
emits::

    src/byteb4rb1e/sphinxcontrib/h5p/<dir_name>/_generated/
    src/byteb4rb1e/sphinxcontrib/h5p/<dir_name>/_static/
    tests/unit/_generated/

The directive and node classes under ``_generated/directive.py``
become importable. Runtime parameter reconstruction lives in
``_generated/params.py``.

4. Install and exercise
-----------------------

Editable-install into the consuming project::

    pipenv install -e <path-to-new-package>

Add the package's ``pip_name`` to the Sphinx project's
``extensions`` list::

    extensions = [
        'byteb4rb1e.sphinxcontrib.xapi.cmi5',
        'byteb4rb1e.sphinxcontrib.h5p.true_false',
    ]

Use the directive in RST::

    .. h5p-true-false::
       :correct: true

       The sphinx-courseware pipeline emits cmi5 packages.

Build the Sphinx project. If the directive renders and the vendored
assets land in ``_static/``, the loop closes.

5. Hand-written overrides
-------------------------

If the semantics walk cannot express the directive's shape (deeply
nested structural children, cross-library references), add a sibling
``directives.py`` next to ``_generated/``. The package's
``__init__.py`` loads manual modules first and falls back to
generated ones — overrides are additive. See :doc:`override-generated`.
