docs: build_qx_extensions, and developing an extension in a container
An extension author is now given `build_qx_extensions` rather than
`build_qx_registry --build_core=no`. The extensions page, the whitepaper
and the worked example all use it: naming what to build, with or without
the `qx_` prefix, several at once or `all`, and `--extensions=check` to ask
what QuNex can see. `--build_core` survives only in the whitepaper's
account of `build_qx_registry`'s own parameters, where the distinction
between the suite's registry and an extension's genuinely is the subject.
Each of the three now covers developing an extension **inside** a
container, which none of them did. The extensions page had no container
section at all. The point in each is the same: the registry is written
beside the extension's own code, so with the folder bound in from the host
the rebuild lands there and survives the container, while the suite's own
registry cannot be rebuilt from inside because it is on a read-only image.
The error QuNex gives for that is shown, along with the reason it names
`build_qx_extensions` rather than leaving the reader to work it out.
The extensions page's troubleshooting table gains a row for a registry
location that cannot be written, and its "Requested command is not
supported" row now points at `--extensions=check` for the case where QuNex
cannot see the extension at all. The command registry page stays about the
core registry, and gains a pointer for the extension author and a note on
the location check.
Every quoted output is from a real run. The whitepaper's summary line was
stale on two counts: it read "In addition to core" where core had been left
alone, and counted "1 extension registries".
docs: document how QuNex extensions are written and run
QuNex can be extended with commands of your own, and until now nothing
described how. The mechanism had also changed: an extension used to
register its commands explicitly, and since the arrival of the command
registry a command is registered by carrying a `.. qx_command:` block in
its docstring, exactly as a command of the suite is. Parameters are
still declared explicitly, and the division of labour between the two
declarations involved was nowhere written down.
Two pages are added and linked from Home. `Whitepaper-Extensions.md`
covers the mechanism end to end: what an extension is made of, where
QuNex looks for one, how commands and their parameters are declared, the
path from a command line to the code, the MATLAB and bash cases, and how
an extension replaces a command the suite provides. `Extensions.md` is
the working guide — the same ground condensed to what is needed while
writing one, cross-linked to the whitepaper and to the command registry
page. `Command-registry.md` gains a pointer to both and a missing row
for the `matlab` command type.
Both pages describe the mechanism as it now behaves, which is not how it
behaved when they were first drafted. An extension no longer depends on
the environment script having seen it: it resolves its Python, MATLAB
and bash code from the registry the command came from, which is the only
way an extension can work inside a running container, where the
environment is sourced once at start-up and cannot be sourced again. So
the pages present two conditions — a folder QuNex can see, and a
registry that describes it — and state separately what sourcing the
environment adds, which is that the per-extension variables land in the
user's shell rather than in QuNex's process. Along with that:
`python/qx_modules` is optional and only names the modules to import
eagerly; an `arglist` entry may carry a description as a fourth element,
and a converter that cannot be called is reported rather than fatal; a
run whose command comes from an extension says so above its parameter
table; `build_qx_registry --build_core=no` is what an extension author
runs, and an extension's registry travels with it because it holds
relative paths. Both pages carry a section on extensions and containers,
which is the deployment shape most installations actually have.
The comments shipped with `Examples/qx_example` are corrected to match:
`qx_modules` no longer claims to be required, the example's `arglist`
shows the four-element form, and the README tells the reader that the
example arrives with its registry already built.
Every claim that changed was checked by running the example extension
against a QuNex installation rather than by reading the source. That run
also corrected one claim nobody had verified: `qunex --a` prints one
`- name: description` line per command, not a space-separated list.