ARROW-3470: [C++] Fix row-wise example

[fsaintjacques]

• Implement the ADD_EXAMPLE cmake function with new ctest label
  example, also covered by the runexample target. This can be
  toggled via the ARROW_BUILD_EXAMPLES option which is ON by default.
• Implement fully working row-wise-conversion-example.cc and add it to
  the default build.
• Update documentation to embed (manually) the newly created example.

[wesm]

This might be conflicting with #2856. Can we include the C++ file in the generated docs without copying it manually?

[xhochy]

We should be able to include a whole file into the Sphinx docs via https://breathe.readthedocs.io/en/latest/directives.html#doxygenfile

I'll merge #2856 as soon as the build passes, so that this PR can rebase on top. We should get rid of the doxygen tutorials completely soon. We may still build the doxygen HTML but only as API docs. All prose documentation should be in Sphinx.

[xhochy]

These builders are only used in the local scope. We should make them simple stack variables without wrapping them into std::shared_ptr.

[fsaintjacques]

I wrapped them out of uniformity. The cost_components_builder has to be in a shared_ptr to be passed to the components_builder. The previous version was wrongly using a std::move then referencing again the (moved out) builder.

Our choice is between:

• 3 local and 1 shared_ptr builder
• 4 shared_ptr builders

I can revert this choice.

[pitrou]

If you want to include the source for a file in a Sphinx document, you can use the literalinclude directive: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-literalinclude

[fsaintjacques]

Yeah, pre #2856 I was looking at Doxygen documentation to achieve this.

[fsaintjacques]

I tend to prefer prose as a single file with prose comments as it allows to copy-paste in a single pass for users. Anyone objects that I go this route? It'll also give CI testing of C++ examples documentation.

[wesm]

No objections here

[fsaintjacques]

@xhochy that would be ready to review

[xhochy]

+1, this is looking good but sadly needs a rebase now.

Anyone: Feel free to merge once build passes.

[wesm]

I left a few other comments

[wesm]

Cruft

[fsaintjacques]

I addressed the comments and replicated what was done to CI scripts with the new tests default to off.

[wesm]

+1, thanks @fsaintjacques! Will merge once the build runs

[pitrou]

The examples should come before the API IMHO.

[fsaintjacques]

I'll let the CI finish, and if it passes I'll push with this tiny change.

[fsaintjacques]

I don't think the failures were related to this change (gandiva micro benchmark), the second one is odd (https://travis-ci.org/apache/arrow/jobs/467085379)

Error message: Invalid: /home/travis/build/apache/arrow/cpp/src/arrow/ipc/json-integration-test.cc:151 code: RecordBatchFileReader::Open(arrow_file.get(), &arrow_reader)
/home/travis/build/apache/arrow/cpp/src/arrow/ipc/reader.cc:624 code: ReadFooter()
File is too small: 0

Concurrency issue?

[wesm]

I've been seeing this pretty consistently https://travis-ci.org/apache/arrow/jobs/467092615#L2567. I opened https://issues.apache.org/jira/browse/ARROW-4008. It's not related to this patch

[fsaintjacques]

I think this is now safe to merge.