Skip to content

Print canonical docs shortlinks in --help, api show, and plugin errors - #2098

Open
waldekmastykarz wants to merge 1 commit into
dotnet:mainfrom
waldekmastykarz:print-canonical-docs-shortlinks
Open

waldekmastykarz wants to merge 1 commit into
dotnet:mainfrom
waldekmastykarz:print-canonical-docs-shortlinks

Conversation

@waldekmastykarz

Copy link
Copy Markdown
Collaborator

Adds stable https://go.devproxy.net?go=<code> docs shortlinks to CLI output so agents and users can find the right docs page without guessing Learn URLs.

Changes

  • --help for every command ends with a Docs: line:
    • root and group commands (e.g. api, cert) → cli
    • leaf commands → cli-<command path> (e.g. cli-api-show, cli-config-get)
    • commands contributed by built-in plugins → <pluginname> (e.g. mocks → mockresponseplugin)
    • commands contributed by third-party plugins → no link (no canonical page)
  • devproxy api show: adds Docs: https://go.devproxy.net?go=api (text) and a docs property (JSON).
  • Plugin errors (load failure, initialization failure, missing URLs to watch, config schema validation): append the plugin's docs link for plugins shipped in DevProxy.Plugins. Third-party plugins keep the original message.
  • New DocsLinks helper in DevProxy.Abstractions/Utils so the CLI never hard-codes Learn paths, plus HelpDocs to resolve per-command links.

Notes

I probed every code the CLI can emit. All resolve except these, which need redirects added on the shortlink service: cli-msgraphdb, cli-cert-remove, websocketmockresponseplugin.

Resolves #2063

Adds stable https://go.devproxy.net?go=<code> links to CLI output so agents
and users can find the right documentation page without guessing Learn URLs:

- Every command's --help ends with a Docs: line (cli, cli-<command>,
  or <pluginname> for commands contributed by built-in plugins)
- devproxy api show includes the Proxy API docs link in text and JSON output
- Plugin load, initialization, and configuration validation errors include
  the plugin's docs link for plugins shipped with Dev Proxy

Closes dotnet#2063

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@waldekmastykarz
waldekmastykarz requested a review from a team as a code owner November 5, 2026 10:46
Copilot AI balanced review requested due to automatic review settings November 5, 2026 10:46

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are reported for the documentation-shortlink changes.

No open issues 🎉

What changed in this PR

Adds canonical documentation shortlinks to Dev Proxy’s CLI output, helping users and agents find relevant documentation without constructing Learn URLs.

Changes:

  • Adds command-specific docs links to help output, including built-in plugin commands while excluding third-party plugins.
  • Includes documentation links in api show text and JSON output and selected built-in plugin error messages.
  • Centralizes shortlink generation and adds tests for command-link resolution.
File Description
DevProxy/​Plugins/​PluginServiceExtensions.cs Adds docs links to built-in plugin load, initialization, and missing-URL errors.
DevProxy/​Commands/​HelpDocs.cs Resolves command-specific links and explicit plugin overrides.
DevProxy/​Commands/​DevProxyHelpAction.cs Appends documentation links to help output.
DevProxy/​Commands/​DevProxyCommand.cs Associates plugin commands with their documentation links.
DevProxy/​Commands/​ApiCommand.cs Adds API documentation links to text and JSON output.
DevProxy.Tests/​HelpDocsTests.cs Tests command-link resolution and third-party exclusion.
DevProxy.Abstractions/​Utils/​DocsLinks.cs Centralizes shortlink generation and built-in plugin identification.
DevProxy.Abstractions/​Plugins/​BasePlugin.cs Adds built-in plugin docs links to configuration validation errors.

Review effort: Balanced

This branch has not been deployed

No deployments
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.

Print canonical docs shortlinks in --help, api show, and plugin errors

2 participants