Links to related plugins in documentation#232
Open
edufuga wants to merge 11 commits into
Open
Conversation
added 5 commits
July 14, 2026 09:56
…ence docs Related plugin IDs showed up as bold, unlinked text — a page had no way to know where any other plugin's page would land. Now a plugin-id-to-path index gets built once up front, and each reference resolves to a relative link before rendering; an unresolvable one fails the build instead of quietly shipping a dead link. Also picked up real test coverage for the new resolution logic and split the suite into unit and integration runs, since one existing test needs a live CO instance — Taskfile and dependencies updated to match.
The build used to wipe the previous docs before it had any idea whether a related-plugin reference would even resolve. A broken one only showed up mid-rebuild, once the old docs were already gone. Now it checks everything up front, reusing the existing resolution check instead of duplicating it, so the failure and its message stay in one place. Also dropped a stale docstring detail that named a count owned by a different function.
Test Results0 tests 0 ✅ 0s ⏱️ Results for commit 4cee713. ♻️ This comment has been updated with latest results. |
added 4 commits
July 17, 2026 14:48
…recomputing it create_plugin_markdown recomputed its own plugin's page path instead of reading it from plugin_paths, which already holds it — that recomputation duplicated the transformer/non-transformer branching and forced a pointless Path-to-string-and-back trip. It now reads the path from the index, and mkdir runs right before the write instead of before path resolution. resolve_related_plugin_links raises a dedicated RelatedPluginReferenceError instead of a bare Exception, build_plugin_paths uses plugin.pluginType instead of a redundant type_id key, and validate_related_plugin_references collects every unresolvable reference before raising once instead of stopping at the first. Tests updated to match.
… on the first resolve_related_plugin_links stopped at the first broken reference, so a plugin with two stale ones only ever surfaced one — now it collects all of them before raising. Duplicate plugin IDs get their own exception instead of a bare Exception. _relative_link's climbing arithmetic gets named variables instead of single letters. The plugin-type key settles on type_id everywhere instead of switching between type_id/plugin_type/category per function.
The existing render test only proved a single cross-type link with a description works — nothing checked same-category links, same-directory links, more than one related plugin on a page, a reference with no description, or a plugin with none at all. Added tests for all of those against the real template output, plus a missing assertion on the existing test that had description data it never actually checked.
edufuga
marked this pull request as ready for review
July 17, 2026 14:17
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Links to related plugins in documentation
Turns the bold, unlinked plugin IDs in each plugin's "Related Plugins" section into working relative links, resolved from a page-path index built once per build and hard-failing on a reference that can't resolve instead of shipping a dead one.
Related Plugins, linked
A related plugin's ID rendered as bold text with no way to know where that other plugin's page actually lived — a transformer referencing an aggregator, or two plugins in different categories, had nothing to resolve that relationship into an actual path.
build_plugin_pathsnow walks every non-deprecated plugin once and builds an ID-to-path index; each plugin'srelatedPluginslist resolves against that index into a relative link before its page renders, climbing out of the current directory and back down into the target's. A reference that doesn't resolve — deprecated, or outside the five walked plugin types — fails the build immediately instead of quietly shipping a dead link.The resolution path
The build used to wipe the previous output directory before anything checked whether the related-plugin references would even resolve, so a broken one only surfaced mid-rebuild, with the old docs already gone. Validation now runs up front, reusing the same resolution check rather than duplicating it.
create_plugin_markdownused to recompute its own page path fromplugin_typeandbase_dirinstead of reading it out of the index already built for exactly that purpose — the recomputation kept the transformer/non-transformer branch logic written twice and forced a round trip through a string just to drop the last path segment; it now reads the path directly from the index. An unresolvable reference and a duplicate plugin ID both used to raise a bareException; each has its own type now. And a plugin with more than one stale reference used to only ever surface the first — resolution now collects every unresolvable reference for a plugin before raising, so a build with several broken references reports all of them at once.Tests
Tests cover resolution, path-index construction, and the render output, split into a unit suite and an integration suite since one test needs a live CO instance, with the unit suite wired into CI. The render output is checked against all four path shapes
_relative_linkcovers — same category, same directory, a shallower page linking to a deeper one, and a different plugin type entirely — a page with more than one related plugin, a reference with no description, and a plugin with no related plugins at all.Part of CMEM-7549.