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.

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

Consistency in markup in docs #431

Open
bwohlberg opened this issue Jul 18, 2023 · 0 comments
Open

Consistency in markup in docs #431

bwohlberg opened this issue Jul 18, 2023 · 0 comments
Assignees
Labels
discussion required Some discussion necessary to decide how to address this issue documentation Improvements or additions to documentation

Comments

@bwohlberg
Copy link
Collaborator

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 bwohlberg added the documentation Improvements or additions to documentation label Jul 18, 2023
@bwohlberg bwohlberg added the discussion required Some discussion necessary to decide how to address this issue label Dec 12, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
discussion required Some discussion necessary to decide how to address this issue documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

2 participants