Align operator and property formatting for existing articles and tutorials

[banchan86]

The formatting of operators and properties is inconsistent across articles and tutorials. Standardizing the formatting will improve the clarity and polish while promoting best practices for future contributions to documentation.

Some examples

Articles

observables, subjects - The first operator reference uses xref, while subsequent operator references and properties use backticks for inline code formatting.
property mapping, higher-order operators - Most operator and property references use xref, but some do not.

Tutorials

acquisition - The first operator and property references use xref, with subsequent references using backticks.
close loop - Operators are formatted with xref, while properties use backticks (but it gradually disappears 😃 )

Proposed alignment

To align with the documentation style guide:

• All operator references should use xref formatting.
• All property references should use backticks for inline code formatting.

While applying this consistently may be more time-consuming than the other approaches, it eliminates the need to track previous mentions (for first reference formatting), reduces inconsistency, and clearly distinguishes operators from properties (avoiding an overuse of excessive highlighting).

[glopesdev]

@banchan86 If we are to apply the current style more strictly throughout articles and tutorials there are definitely things which we should consider improving:

• reduce the amount of repetition required in every reference to an operator
• reduce the possibility of typos when writing the shorthand text of the reference (which is not validated)
• improve the consistency in styles between reference docs and tutorials

One possibility to align everything and improve on these points would be to always use docfx shorthand for all operators in tutorials and articles, i.e. instead of [`CameraCapture`](xref:Bonsai.Vision.CameraCapture) we would instead write @Bonsai.Vision.CameraCapture.

The main difference imposed by the shorthand syntax is that it will resolve to a hyperlink with the class name, but without wrapping the link inside a <code> element, which causes visual differences. I do prefer the visual style we have now, but maybe it's more of a habit. Below I include the two styles for comparison.

Apart from this visual difference, the shorthand syntax would indeed be more practical to enforce usage / correctness since you only write the xref once and it is validated for existence and typos (so you automatically know if you wrote it wrong). Also in the future if we change the style in CSS both conceptual and technical docs will change consistently.

Using @Bonsai.Vision.CameraCapture

Using [`CameraCapture`](xref:Bonsai.Vision.CameraCapture)

[glopesdev]

With or without the docfx shorthand, I do think it is inevitable that we allow people to reference classes and operators through code elements. This will happen naturally when referencing output types, property types, and other mentions to various objects in more complex examples.

I think it will be hard to enforce in practice that every reference to int be replaced with System.Int32, and it will be a slippery slope from there. I think this is why I initially decided to use a xref only for the first time an operator is introduced in the tutorial / article. At that time I think it can be important, since it is a moment when the reader is primed to learn something about how the operator works.

Even the docfx documentation itself uses this hybrid style (incidentally they also use our current style of links wrapped in <code> elements).

[glopesdev]

A third alternative was suggested during the DCM: reference links with implicit link name shortcuts. Implicit link name shortcuts allow us to use any convention of text as the link identifier itself, including markdown styling. Example below:

- Insert a [`CameraCapture`][] operator.
- Insert a second [`CameraCapture`][] operator.

[`CameraCapture`]: xref:Bonsai.Vision.CameraCapture

[banchan86]

A third alternative was suggested during the DCM: reference links with implicit link name shortcuts. Implicit link name shortcuts allow us to use any convention of text as the link identifier itself, including markdown styling. Example below:

• Insert a CameraCapture operator.
• Insert a second CameraCapture operator.

Raised a PR to update the documentation style guide #124. I found out that actually you can even drop the second empty bracket, and rename the operator directly in the reference name portion of the reference style link.