Fix sphinx warnings

[ongchi]

Which issue does this PR close?

None

Rationale for this change

The document building process produces multiple warnings. Some of these warnings are not really a big deal, but some may contains valuable information, and it's really difficult to notice that when a huge warning message is emitted.

What changes are included in this PR?

• Remove/modify some syntax tag of code blocks, since syntax coloring not working but only produces warnings.
• Remove leading ❯ in sql code blocks.
• Fix reference links.
• Fix typos.

Are these changes tested?

No code changed in this PR.

Are there any user-facing changes?

Yes.

[alamb]

Thank you @ongchi -- I have also noticed this and it will be very nice to fix 🙏

[alamb]

It looks like the CI check failure

https://github.com/apache/arrow-datafusion/actions/runs/7795262489/job/21257910229?pr=9142

Can probably be fixed by adding the apprpriate cfg (so it doesn't try to run the examples when the snmalloc crate / option isn't enabled)

[ongchi]

It looks like the CI check failure

https://github.com/apache/arrow-datafusion/actions/runs/7795262489/job/21257910229?pr=9142

Can probably be fixed by adding the apprpriate cfg (so it doesn't try to run the examples when the snmalloc crate / option isn't enabled)

https://github.com/apache/arrow-datafusion/blob/c9e4b7b7c5c2c2e7b3ea01040a6edeafd151410c/datafusion/core/src/lib.rs#L531-L535

https://github.com/apache/arrow-datafusion/blob/c9e4b7b7c5c2c2e7b3ea01040a6edeafd151410c/docs/source/user-guide/example-usage.md?plain=1#L231-L241

This block has been ignored before, and I think it is safe to be ignored since this block is obvious and not likely to undergo any modifications in the future. Alternatively, maybe someday the example usage page could be reorganized, and we can put this block into datafusion-examples instead of datafusion-core.

[ongchi]

I just put a space before the comma. Thankfully, this works with both Rust and Sphinx😎

[alamb]

This is great -- thank you for this very nice contribution @ongchi 🙏

Wow 🤯 -- this is as clean as I have ever seen

(venv) andrewlamb@Andrews-MacBook-Pro:~/Software/arrow-datafusion/docs$ ./build.sh
Running Sphinx v7.2.6
making output directory... done
[autosummary] generating autosummary for: contributor-guide/architecture.md, contributor-guide/communication.md, contributor-guide/index.md, contributor-guide/quarterly_roadmap.md, contributor-guide/roadmap.md, contributor-guide/specification/index.rst, contributor-guide/specification/invariants.md, contributor-guide/specification/output-field-name-semantic.md, index.rst, library-user-guide/adding-udfs.md, ..., user-guide/sql/explain.md, user-guide/sql/index.rst, user-guide/sql/information_schema.md, user-guide/sql/operators.md, user-guide/sql/scalar_functions.md, user-guide/sql/select.md, user-guide/sql/sql_status.md, user-guide/sql/subqueries.md, user-guide/sql/window_functions.md, user-guide/sql/write_options.md
myst v2.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions={'colon_fence', 'tasklist', 'deflist'}, disable_syntax=[], all_links_external=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=3, heading_slug_func=None, html_meta={}, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 39 source files that are out of date
updating environment: [new config] 39 added, 0 changed, 0 removed
reading sources... [100%] user-guide/sql/write_options
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
                  copying downloadable files... [100%] ../../datafusion/core/tests/data/capitalized_example.csv
copying static files... done
copying extra files... done
done
writing output... [100%] user-guide/sql/write_options
generating indices... genindex done
highlighting module code...
writing additional pages... search done
copying images... [100%] _static/images/DataFusion-Logo-Background-White.png
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in build/html.
(venv) andrewlamb@Andrews-MacBook-Pro:~/Software/arrow-datafusion/docs$

I wonder if we should consider adding a github check to make sure the doc build stays warning free 🤔