Skip to content

docs: add plugin discovery docs#642

Merged
johnnygreco merged 1 commit into
johnny/feat/617/plugin-catalog-cli-corefrom
johnny/docs/plugin-discovery-installation
May 13, 2026
Merged

docs: add plugin discovery docs#642
johnnygreco merged 1 commit into
johnny/feat/617/plugin-catalog-cli-corefrom
johnny/docs/plugin-discovery-installation

Conversation

@johnnygreco
Copy link
Copy Markdown
Contributor

📋 Summary

Adds a dedicated Discover Plugins docs page for the new plugin CLI workflow. The page explains catalog-based discovery, package aliases, installation and uninstall commands, alternate catalogs, and the path for future community plugins.

🔗 Related Issue

N/A — stacked on #618.

🔄 Changes

  • Add Discover Plugins docs for both MkDocs and Fern.
  • Rename the docs route from plugins/available to plugins/discover.
  • Update plugin overview pages and nav entries to point readers at the catalog workflow.
  • Remove the old Fern available redirect because this route has not shipped yet.

🧪 Testing

  • git diff --check passes
  • fern check passes
  • uv run mkdocs build passes
  • Unit tests N/A — docs-only change
  • E2E tests N/A — docs-only change

✅ Checklist

  • Follows commit message conventions
  • Commits are signed off (DCO)
  • Architecture docs updated (N/A — user-facing docs only)

Signed-off-by: Johnny Greco <jogreco@nvidia.com>
@johnnygreco johnnygreco requested a review from a team as a code owner May 13, 2026 15:07
@johnnygreco johnnygreco requested a review from eric-tramel May 13, 2026 15:08
@greptile-apps
Copy link
Copy Markdown
Contributor

greptile-apps Bot commented May 13, 2026

Greptile Summary

This PR replaces the placeholder "Available Plugins" docs page with a new "Discover Plugins" page covering the catalog-based CLI workflow, and updates nav entries and cross-links across MkDocs and Fern accordingly.

  • Deletes the available.md/available.mdx placeholder ("Coming Soon") and introduces discover.md/discover.mdx with full CLI command documentation, catalog mechanics, and community plugin guidance.
  • Updates navigation in mkdocs.yml, fern/versions/latest.yml, v0.5.8.yml, and v0.5.9.yml, and removes the now-unnecessary Fern redirect for the unshipped /plugins/available route.
  • Refreshes overview.md/overview.mdx to point readers at the new Discover page instead of the old Available list.

Confidence Score: 5/5

Safe to merge — purely additive documentation with no code changes.

All changes are documentation only: a new page, nav updates, cross-link corrections, and removal of a never-shipped placeholder and its stale redirect. Content is internally consistent between the MkDocs and Fern versions, and the PR description accounts for the stacking dependency on #618.

No files require special attention.

Important Files Changed

Filename Overview
docs/plugins/discover.md New MkDocs page with full catalog-based plugin discovery docs; content is accurate and well-structured
fern/versions/v0.5.8/pages/plugins/discover.mdx New Fern page mirroring discover.md; uses correct Fern component syntax (Note, absolute paths) and is consistent with the MkDocs version
fern/versions/v0.5.8.yml Swaps the nav entry from available.mdx (placeholder) to discover.mdx; consistent with latest.yml and v0.5.9.yml
fern/docs.yml Removes the /plugins/available redirect that was never needed for a shipped route
mkdocs.yml Single nav entry rename from available.md to discover.md; correct
docs/plugins/overview.md Minor wording tweak and cross-link updated from available.md to discover.md
fern/versions/v0.5.8/pages/plugins/overview.mdx Removes the pip install code block from the usage section and redirects readers to the new Discover page

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[plugins/overview] -->|"See Discover Plugins"| B[plugins/discover]
    B --> C["NVIDIA catalog\n(default)"]
    B --> D["Custom catalogs\n(--catalog flag)"]
    C --> E["data-designer plugin list/search/info"]
    D --> E
    E --> F["data-designer plugin install"]
    F --> G["Entry point discovery\ndata_designer.plugins"]
    G --> H["Runtime plugins available"]
    B --> I["Community plugins\n(PyPI + GitHub issue)"]

    style B fill:#4CAF50,color:#fff
    style A fill:#2196F3,color:#fff
Loading

Reviews (1): Last reviewed commit: "add plugin discovery docs" | Re-trigger Greptile

@github-actions
Copy link
Copy Markdown
Contributor

MkDocs preview: https://6229b46c.dd-docs-preview.pages.dev

Fern preview: https://nvidia-preview-pr-642.docs.buildwithfern.com/nemo/datadesigner​

Notebook tutorials are rendered without execution outputs in previews.

@johnnygreco johnnygreco merged commit e04bf77 into johnny/feat/617/plugin-catalog-cli-core May 13, 2026
5 checks passed
johnnygreco added a commit that referenced this pull request May 13, 2026
* feat(cli): add plugin catalog services

Add typed catalog and tap models, persistent tap storage, cached
catalog loading, compatibility evaluation, install plan generation,
and runtime plugin discovery helpers.

Refs #617

* feat(cli): add plugins command group

Wire list, search, info, install, installed, and tap management
commands through the existing command-controller CLI pattern.

Refs #617

* test(cli): cover plugin catalog workflows

Add regression coverage for tap caching, catalog compatibility,
installer command generation, local path resolution, and Typer command
delegation.

Refs #617

* fix(cli): align plugin taps with schema v2

Validate tap catalogs against the schema v2 contract used by
NVIDIA-NeMo/DataDesignerPlugins#36, including source union fields,
docs URLs, package paths, compatibility metadata, and unique runtime
plugin names.

Derive Git install targets as package-qualified PEP 508 direct
references so git tap entries install the package described by the
catalog source metadata.

Refs #617

* fix(cli): address plugin review feedback

- Invalidate import caches before post-install entry point verification
- Make tap aliases case-insensitive and cache catalogs by alias plus URL
- Prefer compatible catalog entries before falling back to forced installs
- Clarify unused --tap behavior and list installed entry points without imports
- Add direct controller coverage and update CLI plugin documentation

Refs #617

* fix(cli): gate incompatible plugin installs

Fetch install targets before compatibility filtering so the controller
owns the final --force decision and the incompatible install guard stays
reachable.

Refs #617

* style(cli): format plugin catalog files

Apply ruff formatting to the plugin command and tap repository tests so
CI format checks pass on the PR merge commit.

Refs #617

* fix(cli): reject duplicate plugin entry names

Key catalog duplicate detection by entry_point.name so distinct catalog
entries cannot register the same runtime plugin name.

Refs #617

* fix(cli): preserve GitHub tree tap paths

* fix(cli): verify plugin entry point names

* align plugin CLI with catalog schema

- adopt catalog terminology for plugin source aliases
- parse package-first plugin catalog metadata from the plugin repo
- install package requirements with optional catalog indexes

* tidy plugin catalog workflow docs

* align plugin catalog CLI with package contract

* add plugin package uninstall workflow

* test plugin package command targets

* document plugin package aliases

* address plugin catalog review feedback

* prefer runtime plugin lookup matches

* rename plugins command to plugin

* show plugin package descriptions

* rename plugin catalogs command

* add protected plugin package installs

* document plugin package install modes

* avoid building project during plugin installs

* harden plugin package installs

* tighten plugin catalog contracts

* fix no-args help exit code

* make plugin docs links robust

* document plugin CLI catalog workflows

* clarify plugin entry point verification

* simplify plugin CLI docs

* narrow plugin search fields

* hide plugin catalog cache ttl

* remove plugin catalog trust flag

* improve plugin CLI recovery UX

* polish plugin catalog table display

* stabilize plugin catalog table test

* tighten plugin catalog edge cases

* harden plugin catalog verification

- Escape catalog-provided Rich markup before rendering CLI output
- Reject runtime plugin names that collide after enum-key normalization
- Load installed runtime entry points in a subprocess before reporting success

* simplify plugin entry point verification

Load matching entry points directly after install instead of spawning a
separate Python process. This keeps the check package-scoped while still
catching broken entry-point targets and non-Plugin objects.

* require newer uv for plugin plans

Use uv >= 0.10.0 as the single supported uv requirement for
plugin package commands. Auto mode now falls back to a pip plan with
an upgrade warning when uv is unavailable or too old, while explicit
uv selection remains strict.

* verify pip fallback availability

* polish plugin CLI status markers

* clarify plugin compatibility labels

* simplify plugin info install details

* address plugin CLI review nits

* support versioned plugin package installs

* share plugin install metadata rendering

* show installed plugin packages

* harden versioned plugin installs

- Preserve catalog requirement constraints for versioned installs
- Remove stale install-plan metadata fields
- Expand parser, uv, controller, and local-catalog dry-run coverage

* harden plugin help tests

* show plugin package versions

Add package version metadata support for plugin catalogs and resolve current versions from exact requirements or simple indexes when catalog entries omit them.

Update plugin list/info/install metadata to show the plugin package version and Data Designer compatibility requirement while removing the separate Data Designer version line.

* format plugin catalog tests

* harden plugin package metadata checks

* harden plugin CLI test coverage

* add plugin discovery docs (#642)

Signed-off-by: Johnny Greco <jogreco@nvidia.com>

---------

Signed-off-by: Johnny Greco <jogreco@nvidia.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant