GH-49509: [Docs][Python][C++] Minimize warnings and docutils errors for Sphinx build html

[tadeja]

Rationale for this change

Closes #49509

What changes are included in this PR?

Docs formatting/typos corrected.

Are these changes tested?

Yes, on fork branch.

Are there any user-facing changes?

No, just corrected formatting/typos in docs.

• GitHub Issue: [Docs][Python][C++] Minimize warnings and docutils errors for Sphinx build html where possible #49509

[tadeja]

Reposting from the issue:

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]
...

[tadeja]

Most of the errors show up as malformed doc pages and correcting these improves doc page readability;

/opt/conda/envs/arrow/lib/python3.12/site-packages/pyarrow/parquet/core.py:docstring of pyarrow.parquet.core.write_table:195: ERROR: Unexpected indentation. [docutils]
/opt/conda/envs/arrow/lib/python3.12/site-packages/pyarrow/parquet/core.py:docstring of pyarrow.parquet.core.write_table:196: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
..

https://arrow.apache.org/docs/dev/python/generated/pyarrow.parquet.write_table.html
Unintentional text boxes within malformed listings of the physical types: - int32:, - fixed_len_byte_array: , and - binary:

• min_chunk_size: and -max_chunk_size:

[tadeja]

https://arrow.apache.org/docs/dev/cpp/env_vars.html broken link, it should be
:py:mod:multiprocessing to link to Python multiprocessing

[tadeja]

Broken bool_ https://arrow.apache.org/docs/dev/python/generated/pyarrow.Bool8Array.html#pyarrow.Bool8Array.from_numpy

and malformed flatten code example

https://arrow.apache.org/docs/dev/python/generated/pyarrow.ListArray.html#pyarrow.ListArray.flatten

docstring of pyarrow.lib.Bool8Array.from_numpy:2: ERROR: Unknown target name: "bool". [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]
docstring of pyarrow.lib.BaseListArray.flatten:49: ERROR: Unexpected indentation. [docutils]
docstring of pyarrow.lib.BaseListArray.flatten:51: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
docstring of pyarrow.lib.BaseListArray.flatten:53: ERROR: Unexpected indentation. [docutils]
docstring of pyarrow.lib.BaseListArray.flatten:55: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
docstring of pyarrow.lib.BaseListArray.flatten:56: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
...
...

[kou]

@github-actions crossbow submit preview-docs

[github-actions]

Revision: 79c71f0

Submitted crossbow builds: ursacomputing/crossbow @ actions-0a3dab5269

Task	Status
preview-docs

[tadeja]

@rok could you do a pass?

[tadeja]

This was the commit adding new ARROW_CUDA_EXPORT and adding it now to Doxyfile resolves these:

/build/python/docs/source/cpp/api/cuda.rst:73: WARNING: Error when parsing function declaration.
If the function has no return type:
  Error in declarator or parameters-and-qualifiers
Error: at 18]
    ARROW_CUDA_EXPORT Result< std::shared_ptr< CudaBuffer > > SerializeRecordBatch (const RecordBatch &batch, CudaContext *ctx)
    ------------------^
...

[tadeja]

I've excluded some unnecessarily complex fixes for now( like this CI change ), so with current fixes we get:
Down from current on main: build succeeded, 129 warnings.
to nicer: build succeeded, 45 warnings.

[rok]

@raulcd quick look perhaps? I'll merge tonight if CI passes.

[raulcd]

I am no expert on sphinx, doxygen or restructured text but all those changes look reasonable to me.