Skip to content

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
@glopesdev
Copy link
Member

@banchan86 Thanks, these look great, do you mind rebasing to resolve the conflicts now that I have merged in some of the other changes?

@banchan86
Copy link
Contributor Author

@glopesdev rebased and resolved the conflicts! Also updated the xrefs for operators from packages that now have docfx websites up (they used to point to the github repository for the package). That also required updated the xrefmaps in docfx.json. The only ones remaining are Bonvision operators in the "Vision Psychophysics" article, they just point to the existing website.

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

2 participants