Merge C++ and Python documentation

cpp/apidoc/Doxyfile

@@ -1919,7 +1919,7 @@ MAN_LINKS              = NO
 # captures the structure of the code including all documentation.
 # The default value is: NO.
 
-GENERATE_XML           = NO
+GENERATE_XML           = YES
 
 # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of

cpp/src/arrow/array.h

@@ -397,6 +397,8 @@ class ARROW_EXPORT PrimitiveArray : public FlatArray {
   const uint8_t* raw_values_;
 };
 
+
+/// Concrete Array class for numeric data.
 template <typename TYPE>
 class ARROW_EXPORT NumericArray : public PrimitiveArray {
  public:

python/doc/.gitignore

@@ -16,4 +16,4 @@
 # under the License.
 
 _build
-source/generated
+source/python/generated

python/doc/source/conf.py

@@ -57,7 +57,8 @@ extensions = [
     'sphinx.ext.viewcode',
     'sphinx.ext.napoleon',
     'IPython.sphinxext.ipython_directive',
-    'IPython.sphinxext.ipython_console_highlighting'
+    'IPython.sphinxext.ipython_console_highlighting',
+    'breathe'
 ]
 
 # Show members for classes in .. autosummary
@@ -77,6 +78,9 @@ napoleon_use_rtype = False
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
+breathe_projects = { "arrow_cpp": "../../../cpp/apidoc/xml" }
+breathe_default_project = "arrow_cpp"
+
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
@@ -93,7 +97,7 @@ autosummary_generate = glob.glob("*.rst")
 master_doc = 'index'
 
 # General information about the project.
-project = u'pyarrow'
+project = u'Apache Arrow'
 copyright = u'2016-2018 Apache Software Foundation'
 author = u'Apache Software Foundation'
 
@@ -180,7 +184,7 @@ html_theme_options = {
 # The name for this set of Sphinx documents.
 # "<project> v<release> documentation" by default.
 #
-# html_title = u'pyarrow v0.1.0'
+# html_title = u'Apache Arrow v0.1.0'
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #
@@ -280,7 +284,7 @@ html_static_path = ['_static']
 # html_search_scorer = 'scorer.js'
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'pyarrowdoc'
+htmlhelp_basename = 'arrowdoc'
 
 # -- Options for LaTeX output ---------------------------------------------
 
@@ -306,7 +310,7 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'pyarrow.tex', u'pyarrow Documentation',
+    (master_doc, 'arrow.tex', u'Apache Arrow Documentation',
      u'Apache Arrow Team', 'manual'),
 ]
 
@@ -348,7 +352,7 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'pyarrow', u'pyarrow Documentation',
+    (master_doc, 'arrow', u'Apache Arrow Documentation',
      [author], 1)
 ]
 
@@ -363,8 +367,8 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'pyarrow', u'pyarrow Documentation',
-     author, 'pyarrow', 'One line description of project.',
+    (master_doc, 'arrow', u'Apache Arrow Documentation',
+     author, 'Apache Arrow', 'One line description of project.',
      'Miscellaneous'),
 ]
 

python/doc/source/cpp/api.rst

@@ -0,0 +1,26 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements.  See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership.  The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License.  You may obtain a copy of the License at
+
+..   http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing,
+.. software distributed under the License is distributed on an
+.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+.. KIND, either express or implied.  See the License for the
+.. specific language governing permissions and limitations
+.. under the License.
+
+*************
+API Reference
+*************
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Getting Started
+
+   api/array

python/doc/source/cpp/api/array.rst

@@ -0,0 +1,81 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements.  See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership.  The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License.  You may obtain a copy of the License at
+
+..   http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing,
+.. software distributed under the License is distributed on an
+.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+.. KIND, either express or implied.  See the License for the
+.. specific language governing permissions and limitations
+.. under the License.
+
+Array types
+=============
+
+.. doxygenclass:: arrow::Array
+   :project: arrow_cpp
+   :members:
+
+.. doxygenclass:: arrow::DictionaryArray
+   :project: arrow_cpp
+   :members:
+
+non-nested array types
+----------------------
+
+.. doxygenclass:: arrow::FlatArray
+   :project: arrow_cpp
+   :members:
+
+.. doxygenclass:: arrow::NullArray
+   :project: arrow_cpp
+   :members:
+
+.. doxygenclass:: arrow::BinaryArray
+   :project: arrow_cpp
+   :members:
+
+.. doxygenclass:: arrow::StringArray
+   :project: arrow_cpp
+   :members:
+
+.. doxygenclass:: arrow::PrimitiveArray
+   :project: arrow_cpp
+   :members:
+
+.. doxygenclass:: arrow::BooleanArray
+   :project: arrow_cpp
+   :members:
+
+.. doxygenclass:: arrow::FixedSizeBinaryArray
+   :project: arrow_cpp
+   :members:
+
+.. doxygenclass:: arrow::Decimal128Array
+   :project: arrow_cpp
+   :members:
+
+.. doxygenclass:: arrow::NumericArray
+   :project: arrow_cpp
+   :members:
+
+nested array types
+------------------
+
+.. doxygenclass:: arrow::UnionArray
+   :project: arrow_cpp
+   :members:
+
+.. doxygenclass:: arrow::ListArray
+   :project: arrow_cpp
+   :members:
+
+.. doxygenclass:: arrow::StructArray
+   :project: arrow_cpp
+   :members:

python/doc/source/cpp/index.rst

@@ -0,0 +1,25 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements.  See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership.  The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License.  You may obtain a copy of the License at
+
+..   http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing,
+.. software distributed under the License is distributed on an
+.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+.. KIND, either express or implied.  See the License for the
+.. specific language governing permissions and limitations
+.. under the License.
+
+C++ Implementation
+==================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Getting Started
+
+   api

python/doc/source/index.rst

@@ -15,8 +15,8 @@
 .. specific language governing permissions and limitations
 .. under the License.
 
-Python bindings for Apache Arrow
-================================
+Apache Arrow
+============
 
 Apache Arrow is a cross-language development platform for in-memory data. It
 specifies a standardized language-independent columnar memory format for flat
@@ -24,31 +24,15 @@ and hierarchical data, organized for efficient analytic operations on modern
 hardware. It also provides computational libraries and zero-copy streaming
 messaging and interprocess communication.
 
-The Arrow Python bindings have first-class integration with NumPy, pandas, and
-built-in Python objects.
+.. toctree::
+   :caption: Memory Format
 
-This is the documentation of the Python API of Apache Arrow. For more details
-on the format and other language bindings see
-`the main page for Arrow <https://arrow.apache.org/>`_. Here will we only
-detail the usage of the Python API for Arrow and the leaf libraries that add
-additional functionality such as reading Apache Parquet files into Arrow
-structures.
+   format
 
 .. toctree::
    :maxdepth: 2
-   :caption: Getting Started
+   :caption: Languages
 
-   install
-   development
-   memory
-   data
-   ipc
-   filesystems
-   plasma
-   numpy
-   pandas
-   csv
-   parquet
-   extending
-   api
-   getting_involved
+   language_interop
+   cpp/index
+   python/index

python/doc/source/python/index.rst

@@ -0,0 +1,47 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements.  See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership.  The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License.  You may obtain a copy of the License at
+
+..   http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing,
+.. software distributed under the License is distributed on an
+.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+.. KIND, either express or implied.  See the License for the
+.. specific language governing permissions and limitations
+.. under the License.
+
+Python bindings
+===============
+
+The Arrow Python bindings have first-class integration with NumPy, pandas, and
+built-in Python objects. They are based on the C++ implementation of Arrow.
+
+This is the documentation of the Python API of Apache Arrow. For more details
+on the format and other language bindings see the parent documentation.
+Here will we only detail the usage of the Python API for Arrow and the leaf
+libraries that add additional functionality such as reading Apache Parquet
+files into Arrow structures.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Getting Started
+
+   install
+   development
+   memory
+   data
+   ipc
+   filesystems
+   plasma
+   numpy
+   pandas
+   parquet
+   extending
+   api
+   getting_involved
+

python/doc/source/python/numpy.rst

@@ -17,8 +17,8 @@
 
 .. _numpy_interop:
 
-Using PyArrow with NumPy
-========================
+NumPy Integration
+=================
 
 PyArrow allows converting back and forth from
 `NumPy <https://www.numpy.org/>`_ arrays to Arrow :ref:`Arrays <data.array>`.

python/doc/source/python/pandas.rst

@@ -17,8 +17,8 @@
 
 .. _pandas_interop:
 
-Using PyArrow with pandas
-=========================
+pandas Integration
+==================
 
 To interface with `pandas <https://pandas.pydata.org/>`_, PyArrow provides
 various conversion routines to consume pandas structures and convert back