scico icon indicating copy to clipboard operation
scico copied to clipboard

Consistency in markup in docs

Open bwohlberg opened this issue 11 months ago • 0 comments

The scico style guide pages calls for single backtick markup for names of entities such as variables, functions, etc., and does not specify the markup to be used for brief inline code snippets. Usage in docs source and code docstrings, however, is wildly inconsistent, with both single and double backticks being used for names, and single and double backticks as well as :code roles being used for brief code snippets.

A decision should be made on the desired markup, and should be included in the style guide and implemented across the docs. The most obvious choice is single backticks for names of variables etc. and double backticks for code snippets, but this ends up being a bit jarring in certain contexts, such as when discussing a variable `x` and its attribute ``x.T``, which are rendered very differently.

bwohlberg avatar Jul 18 '23 14:07 bwohlberg