ARROW-3233: [Python] Add prose documentation for CUDA support

[pitrou]

It will be harder to add generated API docs without requiring CUDA support on the machine building the docs.

[wesm]

Does Sphinx support any kind of feature flags at the rst level? (for the autosummary generated things)

[pitrou]

Not sure what you mean... something like conditional generation?

[pitrou]

Apparently there's the "ifconfig" extension.

[wesm]

Right, what I'm saying is to add some kind of a marker to a section to be ignored if some condition in the configuration file is set (i.e. based on whether a certain module is available or not).

So if there were a section with CUDA functions then they would not appear in the generated version of

https://raw.githubusercontent.com/apache/arrow/master/docs/source/python/api.rst

[pitrou]

I see. I could tackle that in this PR or in another PR/JIRA, as you prefer.

(then we need to upload official docs from a CUDA-enabled machine - or perhaps only the CUDA toolkit is needed? I'm not sure)

[wesm]

I'm not sure either. Now that UL has some physical CUDA-enabled hardware I would be fine with giving committers non-sudo accounts with the ability to use nvidia-docker to build the docs in a CUDA-equipped environment, so that is one way around this at least

[wesm]

Either here or another PR is fine with me. Having these initial docs for the 0.12 release would be useful even if the Python packages won't have CUDA support yet

[pitrou]

I'm thinking mainly about automated builds. I have CUDA installed locally myself ;-)

[pitrou]

Ok, I'm gonna merge this PR and open a JIRA for the API docs, then.

[wesm]

Ah, I see. As soon as we have a Jenkins-like automation tool configured we can run nightly docs builds on these machines