Skip to content

Align operator and property formatting for existing articles and tutorials #128

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from

Conversation

banchan86
Copy link
Contributor

Fixes #122 with the new standard formatting for operators and properties.

Changes Implemented

  • Inline xref links for operators were replaced with reference-style xref links. If an operator had no xref and was only highlighted with inline code formatting, a reference-style link was added.
    • For consistency, even if an operator was referenced only once, inline xref links were converted to reference-style links if the article was modified to use reference-style links.
  • Inline xref links for properties were removed, leaving only inline code formatting.
  • Inline xref links for cross-references to other articles or external types were not converted.
    • While these could be converted to reference-style links, I opted to leave them as is to maintain a clear distinction between operator references and other links in the codebase.

Issues Encountered

  • Operators from packages that do not currently have a docfx reference page:

    • For packages with no documentation at all (eg. 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.
    • For Bonvision, I have included a normal html link to the bonvision doc reference page, even though its not updated.
    • For Bonsai.Editor.Scripting operators are missing from technical reference #126 i opted not to reference them at all.

    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):

    • Reference-style links were included in the individual include markdown files rather than the root article.
    • Since include markdown files are often used as Reference overwrite sections, placing reference-style links in the root article would not propagate them to the Reference 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 the include sections.
    • Some operator xref links in the root article were pointing to section links rather than API references. Adding reference-style links in the corresponding include 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 contain xref 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 other include markdown files intended for overwrite in the Reference section.

@banchan86 banchan86 requested a review from glopesdev February 12, 2025 03:41
@banchan86 banchan86 added the documentation Improvements or additions to documentation label Feb 12, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Align operator and property formatting for existing articles and tutorials
1 participant