sphinx-doc / sphinx-doc/sphinx

C++domain: Idiomatic spacing of ptr-operator and ref-qualifier

Open
#7,491 6 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

domains:c domains:cpp type:enhancement
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Problem

When declaring objects (e,g, types, members, functions) in the cpp domain, sphinx accepts
arbitrary spacing between types, cv-qualifiers and ref-qualifiers. It then produces output
in a consistent way (which is a plus) but which cannot be influenced by the user (which is a problem).

For example

cpp:function:: int& foo(const Type & value, Resource * resource)

leads to output

int &foo(const Type &value, Resource *resource)

The problem here is that the spacing chosen by sphinx is not the idiomatic way used by the C++ community (I am aware that this is a bold statement, but https://en.cppreference.com and https://github.com/cplusplus/draft are good support for this.)

An idiomatic spacing for the example above should look somewhat like

int& foo(const Type& value, Resource* resource)

This is important, since IMO documentation should look like the code we write and it should follow conventions which are common in the specific language.

Supporting this kind of spacing could lead more C++ developers to consider using sphinx for documentation.

Possible solutions

  1. All spacing added by the user in the sphinx declarations are transfered as is to the output.
  2. A new option for the C++ domain, say cpp_idiomatic_spacing is added which produces the desired output. The default leaves the output as is.
  3. Sphinx only generates the "idiomatic" output and nothing else.
Option 1

This probably requires huge changes to the output generating functions in cpp.py.
It would make the output depend entirely on the user input. This can be seen as an advantage (full control for the user), but also as a disadvantage (potential for inconsistent output).

Option 2

Feasible, but would lead to lots of branching and duplication in the code and the tests.
The question is whether someone would still want the default behavior once the option is available and if the effort maintaining two output variants is worth while.

Option 3

Implementable with relatively low effort.

Since the current choice of spacing by sphinx is somewhat arbitrary (or taken over from Python or C), a different spacing should be just as good. I am not sure, however, if this would still be considered a breaking change.

Suggested solution

I would appreciate feedback to the above suggestions.
Personally I favor option 3 and would be willing to contribute a PR.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the C++ domain implementation in cpp.py and the issue's three proposed spacing strategies. Check the existing output-generation behavior and related tests, if present, before choosing whether the change should be universal or configurable. Done means the chosen spacing behavior is implemented consistently and its compatibility impact is understood.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp, python
Domain
documentation, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.