Skip to content
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.

Sign up for GitHub

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

Update operator formatting guidelines with reference style link method #124

Merged
merged 2 commits into from
Feb 3, 2025
Merged

Update operator formatting guidelines with reference style link method #124

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
85c98be
Update operator formatting with new reference link method
banchan86 Feb 3, 2025
cae6fbc
Clarify note for reference name change
banchan86 Feb 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 15 additions & 6 deletions articles/documentation-style-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,23 +173,32 @@ Highlight folders, filenames, package names, functions, actions, editor/website

### Standard formatting for operators and operator properties

When referring to operators (also known as nodes in Bonsai), place them inside a pair of backticks (`` `Operator_name` ``). Link the name to the relevant documentation in the code base, using the [markdown syntax for xref in docfx](https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html).
When referring to operators (also known as nodes in Bonsai), use [reference style links](https://www.markdownguide.org/basic-syntax/#reference-style-links) in combination with a [xref](https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html).

For example, the `DigitalOutput` node is part of the `Bonsai.Arduino` namespace/package. To create a reference to this node you need to specify the fully qualified name of the operator, including its namespace, like so: `xref:Bonsai.Arduino.DigitalOutput`. To find out the fully qualified name for any node, right-click on the operator of interest in Bonsai and select the option "Go to Definition" or hit `F12`.
For example, the `DigitalOutput` node is part of the `Bonsai.Arduino` namespace/package. To create a reference link to this node, you need to specify a reference name along with an `xref` containing the fully qualified name of the operator, including its namespace, like so: ```[`DigitalOutput`]: xref:Bonsai.Arduino.DigitalOutput```. The reference style links can be included anywhere in the article. Wherever you would reference the operator, simply use the reference name, by enclosing the operator name in a pair of backticks and square brackets, like this: ``[`DigitalOutput`]``.

To find out the fully qualified name for any node, right-click on the operator of interest in Bonsai and select the option "Go to Definition" or hit `F12`.

When referring to operator properties, simply place the operator property name inside a pair of backticks (`` `Operator_property_name` ``).

**Example:**

```markdown
### **Exercise 7:** Control an LED
- Insert a [`Boolean`](xref:Bonsai.Expressions.BooleanProperty) source.
- Insert a [`DigitalOutput`](xref:Bonsai.Arduino.DigitalOutput) sink.
- Set the `Pin` property of the [`DigitalOutput`](xref:Bonsai.Arduino.DigitalOutput) operator to 13.
- Insert a [`Boolean`] source.
- Insert a [`DigitalOutput`] sink.
- Set the `Pin` property of the [`DigitalOutput`] operator to 13.
- Configure the `PortName` property.
- Run the workflow and change the `Value` property of the [`Boolean`](xref:Bonsai.Expressions.BooleanProperty) operator.
- Run the workflow and change the `Value` property of the [`Boolean`] operator.

<!--Reference Style Links -->
[`Boolean`]: xref:Bonsai.Expressions.BooleanProperty
[`DigitalOutput`]: xref:Bonsai.Arduino.DigitalOutput
```

> [!NOTE]
> The reference name does not need to match the operators fully qualified name in the `xref`.

You can also link to operators in other packages if their [xrefmap](./documentation-docfx.md#configuring-docfx) is included in `docfx.json`.

### Bonsai workflows
Expand Down