Add 'doc_url' parameter to log.error/warning - #3764
Open
ipspace wants to merge 3 commits into
Open
Conversation
The 'doc_url' parameter can be used to point the user to a particular
documentation section while displaying an error message. The hint
is usually formatted as "see also: {url}" unless the caller also
specifies the format string (doc_url_text).
Proof-of-concept implementation in some error messages in STP module.
Contributor
There was a problem hiding this comment.
Pull request overview
Adds first-class support for attaching documentation links to user-facing errors/warnings, allowing modules to emit a “see also” hint that can be customized per call and deduplicated across repeated messages.
Changes:
- Extend
netsim.utils.log.error()(and thuslog.warning()) withdoc_url/doc_url_textand printing logic. - Add
defaults.const.doc_url_prefixand update STP module errors to include doc pointers as a proof-of-concept. - Add developer documentation and new/updated test fixtures for the STP doc URL behavior.
Reviewed changes
Copilot reviewed 6 out of 9 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
netsim/utils/log.py |
Implements doc_url/doc_url_text support and prints deduplicated documentation hints. |
netsim/modules/stp.py |
Adds documentation pointers to select STP validation errors. |
netsim/defaults/const.yml |
Introduces doc_url_prefix used to build full internal documentation URLs. |
docs/module/stp.md |
Adds stable anchors used by doc_url references and updates STP docs tip content. |
docs/dev/error-doc-url.md |
Documents how to use doc_url and why stable source anchors should be used. |
docs/dev/advanced.md |
Adds the new developer doc to the advanced dev-docs ToC. |
tests/errors/stp-on-l3-intf.log |
Updates expected output to include the “See also” hint. |
tests/coverage/errors/stp-doc-url-platform.yml |
Adds a coverage test topology for STP platform doc URL output. |
tests/coverage/errors/stp-doc-url-platform.log |
Adds expected output fixture (currently appears to be a local crash trace). |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+195
to
+202
| if '://' not in doc_url: | ||
| doc_url_pfx = global_vars.get_const('doc_url_prefix') | ||
| doc_url = doc_url_pfx + doc_url | ||
|
|
||
| doc_txt = strings.eval_format(doc_url_text,{'url': doc_url}) | ||
| if doc_txt not in _HINTS_CACHE: | ||
| print_more_hints([ doc_txt ],h_name='DOCS',h_warning=h_warning,indent=indent) | ||
| _HINTS_CACHE.append(doc_txt) |
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
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.
The 'doc_url' parameter can be used to point the user to a particular documentation section while displaying an error message. The hint is usually formatted as "see also: {url}" unless the caller also specifies the format string (doc_url_text).
Proof-of-concept implementation in some error messages in STP module.