sphinx-doc / sphinx-doc/sphinx
C++domain: Idiomatic spacing of ptr-operator and ref-qualifier
Nobody has claimed this yet.
- 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
- All spacing added by the user in the sphinx declarations are transfered as is to the output.
- A new option for the C++ domain, say
cpp_idiomatic_spacingis added which produces the desired output. The default leaves the output as is. - 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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