[DOC]: Format function signatures

[gevtushenko]

Is this a duplicate?

• [x] I confirmed there appear to be no duplicate issues for this bug and that I agree to the Code of Conduct

Is this for new documentation, or an update to existing docs?

New

Describe the incorrect/future/missing documentation

After transitioning to Sphinx-based documentation, we've lost formatting of function signatures along with the majority of syntax highlighting. This makes reading reference documentation an actual challenge:

We should investigate if there's any way to a) format function signatures to at least get each parameter on a new line, b) return syntax highlighting.

If this is a correction, please provide a link to the incorrect documentation. If this is a new documentation request, please link to where you have looked.

No response

[bryevdv]

After some investigation, there is supposedly a Sphinx-level config cpp_maximum_signature_line_length that should control this. I have attempted to build locally with:

sphinx_conf_py_extra = """
cpp_maximum_signature_line_length = 20
"""

added to the [repo_docs.projects.cub] section of repo.toml but this did not have any effect. It's possible out version of repo_docs is too old for the sphinx_conf_py_extra (have not heard back confirmation yet). Repo docs folks suggested updating to > 1.0 anyway, since the formatting should be also be improved automatically:

repo_docs v1 provides some improvements here. In particular, it will shift to argument-per-line if the signature length exceeds 70 characters.

However, it is not currently widely available:

Sidenote: If you need to run repo_docs outside the network, we would advise you do not jump to repo_docs version 1.0 since it is not available outside our network.

Waiting to hear back when it might be usable in "public" and then will first try updating to see if that improves things on its own.

[bryevdv]

Replies from Andrew:

repo_docs <1 uses a much older version of Sphinx, and that particular setting only came in at Sphinx 7.1 unfortunately

and

repo_docs being public is separate from the theme being public (thankfully), and the aim is to make repo_docs public but I don't have a timeframe on that at the moment

So unfortunately I am not sure that a "full" short-term solution would be available, since checking in the newer versions to public repos is not permissible. There might be some CSS tricks to play.

[bryevdv]

OK this small CSS change will offer some relief

/* Newlines (\a) and spaces (\20) before each parameter */
dl.cpp.function .sig-param::before {
    content: "\a\20\20\20\20";
    white-space: pre;
}
/* Newline after the last parameter (so the closing bracket is on a new line) */
dl.cpp.function dt em.sig-param:last-of-type::after {
    content: "\a";
    white-space: pre;
}

[bryevdv]

Per offline discussion I will investigate building the docs with "plain" sphinx, so that the version of sphinx can be updated, and relevant options can be enabled directly via standard conf.py.