GH-50257: [CI][Docs] Fix doxygen failing due to double backticks

[raulcd]

Rationale for this change

Doxygen is currently failing on main

What changes are included in this PR?

Remove double backticks because they trip doxygen.

Are these changes tested?

I have tested them locally with:
archery docker run conda-python-docs

Without the change I could reproduce the CI issue. With the change the job is successful.

Are there any user-facing changes?

No

• GitHub Issue: [CI][Docs] doxygen fails with unsupported xml/html tag <typename> found on /arrow/cpp/src/arrow/util/bit_util.h:249 #50257

[github-actions]

⚠️ GitHub issue #50257 has been automatically assigned in GitHub to PR creator.

[pitrou]

@AntoinePrv FYI

[pitrou]

If it fixes the CI then good 🤷

[raulcd]

@pitrou let's not merge yet, this fixed doxygen but I think the docs job still fail due to the last PR merged also breaking docs:

• GH-38849: [C++][Parquet] Add support for list view and large list view #50160

I can see some doctest failures locally now that the job has run to completion:

/opt/conda/envs/arrow/lib/python3.10/site-packages/pyarrow/lib.cpython-310-x86_64-linux-gnu.so:5953: DocTestFailure
____________________________________________________________________________________________ [doctest] pyarrow.lib.table _____________________________________________________________________________________________
6107 -- schema metadata --
6108 n_legs: 'Number of legs per animal'
6109 
6110 Construct a Table from pandas DataFrame:
6111 
6112 >>> import pandas as pd
6113 >>> df = pd.DataFrame({'year': [2020, 2022, 2019, 2021],
6114 ...                    'n_legs': [2, 4, 5, 100],
6115 ...                    'animals': ["Flamingo", "Horse", "Brittle stars", "Centipede"]})
6116 >>> pa.table(df)
Differences (unified diff with -expected +actual):
    @@ -2,5 +2,5 @@
     year: int64
     n_legs: int64
    -animals: large_string
    +animals: string
     ----
     year: [[2020,2022,2019,2021]]

[raulcd]

It seems to be passing on CI and not related to the issue I pointed. It might be a stale local environment from my side. As I can't reproduce on CI, I think we can ignore my local failure.

[tadeja]

I've just confirmed locally that replacing double backticks with single backtics indeed allowed doxygen to complete, docs got built and pytest -r s --doctest-modules --doctest-cython --pyargs pyarrow passed for me. 👍

Just a note on that local doctest failure @raulcd

-animals: large_string
+animals: string

It's because of pandas version pre 3.0 (which still allows python 3.10 ... but doctest CI job got updated from conda-python-3.10 to conda-python-3.11 as per Joris' #49088 (comment):

FWIW, I think if we know the doctests will run on an instance with pandas>=3, I would just update those to use pandas 3 output, because that will be less confusing for people reading the docs ("what do those 3 dots mean here?").