[Docs] Reduce Sphinx warnings when building html

[tadeja]

Describe the enhancement requested

The latest Docs CI jobs on main

1. AMD64 Debian 12 Complete Documentation
   build succeeded, 26 warnings.
   and
2. AMD64 Conda Python 3.12 Sphinx Documentation
   build succeeded, 55 warnings.

Details

1.

Running Sphinx v9.1.0
...
building [html]: ...
...
/build/python/docs/source/cpp/api/compute.rst:58: WARNING: Too many template argument lists compared to parameter lists. Argument lists: 1, Parameter lists: 0, Extra empty parameters lists prepended: 1. Declaration:
	std::vector<SortKey> [source_code_parser.cpp]
Error: at 60]
  ARROW_UNSUPPRESS_DEPRECATION_WARNING std::vector< SortKey > sort_keys
  ------------------------------------------------------------^
/build/python/docs/source/cpp/api/compute.rst:58: WARNING: Error when parsing function declaration.
If the function has no return type:
  Error in declarator or parameters-and-qualifiers
Error: at 42]
    inline ARROW_SUPPRESS_DEPRECATION_WARNING std::vector< SortKey > GetSortKeys () const
    ------------------------------------------^
...
/build/python/docs/source/cpp/api/dataset.rst:62: WARNING: Parsing of expression failed. Using fallback parser. Error was:
Error in postfix expression, expected primary expression or type.
If primary expression:
Error: at 59]
    std::function< Status(FileWriter *)> writer_pre_finish   = [](FileWriter*) {returnStatus::OK();}
    -----------------------------------------------------------^
If type:
Error: at 59]
    std::function< Status(FileWriter *)> writer_pre_finish   = [](FileWriter*) {returnStatus::OK();}
    -----------------------------------------------------------^
 [source_code_parser.cpp]

and
2.

Running Sphinx v8.2.3
...
/build/python/docs/source/cpp/api/dataset.rst:48: WARNING: Parsing of expression failed. Using fallback parser. Error was:
Error in postfix expression, expected primary expression or type.
If primary expression:
Error: at 80]
    acero::BackpressureOptions backpressure   =                                     = acero::BackpressureOptions::DefaultBackpressure()
    --------------------------------------------------------------------------------^
If type:
Error: at 80]
    acero::BackpressureOptions backpressure   =                                     = acero::BackpressureOptions::DefaultBackpressure()
    --------------------------------------------------------------------------------^
...

Component(s)

Documentation

[pitrou]

Issue resolved by pull request 50396
#50396