Skip to content

Change sphinx default role to "any" - #40

Merged
c24t merged 3 commits into
open-telemetry:masterfrom
c24t:sphinx-better-default-role
Jul 8, 2019
Merged

Change sphinx default role to "any"#40
c24t merged 3 commits into
open-telemetry:masterfrom
c24t:sphinx-better-default-role

Conversation

@c24t

@c24t c24t commented Jul 2, 2019

Copy link
Copy Markdown
Member

This PR changes the sphinx default role so that comments in single-backticks render as literal text and link(!) to the appropriate section of the docs if sphinx can find one.

This recommendation comes from the sphinx docs:

This role is a good candidate for setting default_role. If you do, you can write cross-references without a lot of markup overhead.

One downside is that sphinx can't find a target for some text it'll emit a warning:

docstring of opentelemetry.trace:9: WARNING: 'any' reference target not found: BlankSpan

but we can get around this by using double-backticks to specify the :code: role, which is what we were doing before this change anyway.

@c24t c24t changed the title Change sphinx default role to "any", update docs Change sphinx default role to "any" Jul 2, 2019
@c24t
c24t merged commit d78ea98 into open-telemetry:master Jul 8, 2019
@c24t
c24t deleted the sphinx-better-default-role branch July 8, 2019 20:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants