Add a way to cross-reference code in prose text

[cjdb]

Is your feature request related to a problem? Please describe. It's sometimes easier to refer to a part of an API by describing it, rather than by directly naming it, but the C++ cross-reference directives only render in monospace font.

For example:

and the type of ``x <=> y`` :cpp:type:`can be reduced to \`\`Cat\`\`.<std::common_comparison_category>`

will be rendered as

and the type of x <=> y [can be reduced to ``Cat``.]()

Describe the solution you'd like It should be possible to render the above as

and the type of x <=> y [can be reduced to Cat.]()

I noticed that there's :cpp:expr: and :cpp:texpr:. Perhaps there should be a t-prefixed cross-reference for all of the API cross-references (e.g. cpp:ttype).

[jfbu]

Does using custom CSS styling help? I defined a file _static/custom.css with these contents

code.cpp-type > .pre {
   font-style: normal;
   font-family: roman;
   font-weight: normal;
   /*text-decoration: underline*/
}

as a test and it appears to work (with default html_static_path = ['_static'] in conf.py) (although the escaped ` will show literally)

(but this is limited to html builds)

[cjdb]

Won't this apply to all :cpp:types? I'm documenting the C++ standard library---which is huge---and so I'm going to be alternating between prose and code as it makes sense.

[jfbu]

Won't this apply to all :cpp:types? I'm documenting the C++ standard library---which is huge---and so I'm going to be alternating between prose and code as it makes sense.

Yes you do need a novel role for your task.

[cjdb]

I'll probably make an extension for this soonish (it's not a high priority). Would there be any concerns with upstreaming the roles? I'd make them for all supported languages in that case, not just C++.

[AA-Turner]

A thought -- could you use a custom interpreted text role and add :class: inline-text or etc to it?

xref: https://docutils.sourceforge.io/docs/ref/rst/directives.html#custom-interpreted-text-roles

A

[AA-Turner]

Additionally -- I believe that using texpr should work in general -- are there cases in C++ where the general texpr role doesn't work and you need to use the specific roles?

A

[cjdb]

A thought -- could you use a custom interpreted text role and add :class: inline-text or etc to it?

Possibly? My plan was to copy the cpp:type role and tweak it so that it could be distinct in the CSS.

Additionally -- I believe that using texpr should work in general -- are there cases in C++ where the general texpr role doesn't work and you need to use the specific roles?

I haven't come across anything yet. My understanding of texpr is that it matches names in that role against names registered with C++ directives, but I have an English sentence that needs to be linked to a cpp:type directive.