Consistency in markup in docs #431
Labels
discussion required
Some discussion necessary to decide how to address this issue
documentation
Improvements or additions to documentation
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.
The text was updated successfully, but these errors were encountered: