Align operator and property formatting for existing articles and tutorials #128
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.
Fixes #122 with the new standard formatting for operators and properties.
Changes Implemented
xref
links foroperators
were replaced with reference-stylexref
links. If an operator had noxref
and was only highlighted with inline code formatting, a reference-style link was added.xref
links were converted to reference-style links if the article was modified to use reference-style links.xref
links forproperties
were removed, leaving only inline code formatting.xref
links for cross-references to other articles or external types were not converted.Issues Encountered
Operators from packages that do not currently have a
docfx
reference page:PythonTransform
), I have included a link to the nuget package instead. I figured this would serve as a signpost for people to look for the package in the Bonsai package manager, even though I know its not ideal.This preserves the operator formatting, but I recognize some of these changes might be controversial, so I have placed them at the end of the reference-style link section so that they can be easily removed. It also serves as a reminder to replace those links when we address them
Articles containing
include
markdown files (e.g., Subjects):include
markdown files rather than the root article.include
markdown files are often used asReference
overwrite sections, placing reference-style links in the root article would not propagate them to theReference
page. It just occurred to me that I was writing this up that I'm not sure that reference-style links placed in the root article would propagate to theinclude
sections.xref
links in the root article were pointing to section links rather than API references. Adding reference-style links in the correspondinginclude
markdown files did not interfere with those section links. Just something to take note of.This has the effect that in
Reference
pages where overwrite sections exist, operator references now containxref
links pointing to their own page. While this maintains consistency in operator formatting, self-referencing links may not be ideal. We can discuss whether this change is desirable. For now, I have chosen not to apply this formatting to otherinclude
markdown files intended for overwrite in theReference
section.