[Docs][Python][C++] Minimize warnings and docutils errors for Sphinx build html where possible #49509
Description
Describe the enhancement requested
When building html with sphinx-build -j auto -b html there are several warnings and docutils warnings/errors logged and for several causes can be eliminated.
Examples of CI logs
AMD64 Conda Python 3.11 Sphinx & Numpydoc
AMD64 Debian 12 Complete Documentation
AMD64 Conda Python 3.12 Sphinx Documentation
/opt/conda/envs/arrow/lib/python3.12/site-packages/numpydoc/docscrape.py:203: UserWarning: potentially wrong underline length...
Example
-------- in
...
/opt/conda/envs/arrow/lib/python3.12/site-packages/pyarrow/compute.py:docstring of pyarrow.compute.atanh_checked:4: ERROR: Undefined substitution referenced: "x". [docutils]
docstring of pyarrow.lib.BaseListArray.flatten:44: ERROR: Unexpected indentation. [docutils]
docstring of pyarrow.lib.BaseListArray.flatten:47: WARNING: Definition list ends without a blank line; unexpected unindent. [docutils]
...
/build/python/docs/source/cpp/api/cuda.rst:73: WARNING: Error when parsing function declaration
...
WARNING: unknown role name: python:mod
/build/python/docs/source/cpp/env_vars.rst:96: ERROR: Unknown interpreted text role "python:mod". [docutils]
...
/build/python/docs/source/format/Security.rst:62: WARNING: undefined label: '_format_columnar' [ref.ref]
/build/python/docs/source/format/Security.rst:173: WARNING: undefined label: '_ipc-message-format' [ref.ref]
...
Component(s)
Documentation, Python