westonpace commented on a change in pull request #22: URL: https://github.com/apache/arrow-cookbook/pull/22#discussion_r692533907
########## File path: cpp/CONTRIBUTING.md ########## @@ -0,0 +1,170 @@ +# Bulding the C++ Cookbook + +The C++ cookbook combines output from a set of C++ test programs with +an RST document tree rendered with sphinx. + +Running `make py` from the cookbook root directory (the one where +the `README.rst` exists) will install all necessary dependencies, +run the tests to generate the output, and will compile the cookbook +to HTML. + +You will see the compiled result inside the `build/cpp` directory. + +The above process requires conda to be installed and is primarily +intended for build systems. See below for more information on setting +up a development environment for developing recipes. + +# Developing C++ Recipes + +Every recipe is a combination of prose written in **reStructuredText** +format using the `Sphinx <https://www.sphinx-doc.org/>`\_ documentation +system and a snippet of a googletest test. + +New recipes can be added to one of the existing `.rst` files if +they suit that section or you can create new sections by adding +additional `.rst` files in the `source` directory. You just +need to remember to add them to the `index.rst` file in the +`toctree` for them to become visible. + +## Referencing a C++ Snippet + +Most recipes will reference a snippet of C++ code. For simplicity +a custom `recipe` directive htat can be used like so: + +``` +.. recipe:: ../code/creating_arrow_objects.cc CreatingArrays + :caption: Creating an array from C++ primitives + :dedent: 4 +``` + +Each `recipe` directive has two requried arguments. The first is +a path to the file containing the source file containing the snippet +and the second is the name of the snippet and must correspond to a +set of CreateRecipe/EndRecipe calls in the source file. + +The directive will generate two code blocks in the cookbook. The first +code block will contain the source code itself and will be annotated +with any (optional) caption specified on the recipe directive. The +second block will contain the test output. + +The optional `dedent` argument should be used to remove leading white +space from your source code. + +## Writing a C++ Snippet + +Each snippet source file contains a set of +[googletest](https://github.com/google/googletest) tests. Feel free to +use any googletest features needed to help setup and verify your test. +To reference a snippet you need to surround it in `BeginRecipe` and +`EndRecipe` calls. For example: + +``` +StartRecipe("CreatingArrays"); +arrow::Int32Builder builder; +ASSERT_OK(builder.Append(1)); +ASSERT_OK(builder.Append(2)); +ASSERT_OK(builder.Append(3)); +ASSERT_OK_AND_ASSIGN(shared_ptr<arrow::Array> arr, builder.Finish()) +rout << arr->ToString() << endl; +EndRecipe("CreatingArrays"); +``` + +The variable `rout` is set to a `std::ostream` instance that is used to +capture test output. Anything output to `rout` will show up in the recipe +output block when the recipe is rendered into the cookbook. + +## Referencing Arrow C++ Documentation + +The Arrow project has its own documentation for the C++ implementation that +is hosted at https://arrow.apache.org/docs/cpp/index.html. Fortunately, +this documentation is also built with Sphinx and so we can use the extension +`intersphinx` to reference sections of this documentation. To do so simply +write a standard Sphinx reference like so: + +``` +Typed subclasses of :cpp:class:`arrow::ArrayBuilder` make it easy +to efficiently create Arrow arrays from existing C++ data +``` + +A helpful command is +`python -msphinx.ext.intersphinx https://arrow.apache.org/docs/objects.inv` +which will list all of the possible targets to link to. + +# Development Workflow + +Running `make` at the top level can be rather slow as it will rebuild the +entire environment each time. It is primarily intended for use in CI and +requires you to have conda installed. + +For recipe development you are encouraged to create your own out-of-source +cmake build. For example: + +``` +mkdir cpp/code/build +cd cpp/code/build +cmake ../code -DCMAKE_BUILD_TYPE=Debug +cmake --build . +ctest +``` + +Then you can rerun all of the tests with `ctest` and you can rebuild and +rerun individual tests much more quickly with something like +`cmake --build . --target creating_arrow_objects && ctest creating_arrow_objects`. +Everytime the cmake build is run it will update the recipe output file +referenced by the sphinx build so after rerunning a test you can visualize the +output by running `make html` in the `cpp` directory. + +## Using Conda + +If you are using conda then there is file `cpp/requirements.yml` which can be +used to create an environment for recipe development with the command: + +``` +conda env create -n cookbook-cpp --file cpp/requirements.yml +``` + +# Development Philosophy + +## Everything is the Cookbook + +The entire document should serve as an example of how to use Arrow C++, not just the +referenced snippets. This means that the below style rules and guidelines apply to +source code that is not referenced by the cookbook itself. + +## Style + +This cookbook follows the same style rules as Arrow C++ which is the Google style +guide with a few exceptions described +[here](https://arrow.apache.org/docs/developers/cpp/development.html#code-style-linting-and-ci) Review comment: This is a markdown file. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
