Adding upstream version 18.2.2.upstream/18.2.2

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 103 insertions, 0 deletions

diff --git a/src/arrow/docs/source/developers/documentation.rst b/src/arrow/docs/source/developers/documentation.rst
new file mode 100644
index 000000000..813cc9cbd
--- /dev/null
+++ b/src/arrow/docs/source/developers/documentation.rst
@@ -0,0 +1,103 @@
+.. 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.
+
+.. _building-docs:
+
+Building the Documentation
+==========================
+
+Prerequisites
+-------------
+
+The documentation build process uses `Doxygen <http://www.doxygen.nl/>`_ and
+`Sphinx <http://www.sphinx-doc.org/>`_ along with a few extensions.
+
+If you're using Conda, the required software can be installed in a single line:
+
+.. code-block:: shell
+
+   conda install -c conda-forge --file=ci/conda_env_sphinx.txt
+
+Otherwise, you'll first need to install `Doxygen <http://www.doxygen.nl/>`_
+yourself (for example from your distribution's official repositories, if
+using Linux).  Then you can install the Python-based requirements with the
+following command:
+
+.. code-block:: shell
+
+   pip install -r docs/requirements.txt
+
+Building
+--------
+
+.. note::
+
+   If you are building the documentation on Windows, not all sections
+   may build properly.
+
+These two steps are mandatory and must be executed in order.
+
+#. Process the C++ API using Doxygen
+
+   .. code-block:: shell
+
+      pushd cpp/apidoc
+      doxygen
+      popd
+
+#. Build the complete documentation using Sphinx.
+
+   .. note::
+
+      This step requires the pyarrow library is installed
+      in your python environment.  One way to accomplish
+      this is to follow the build instructions at :ref:`python-development`
+      and then run ``python setup.py install`` in arrow/python
+      (it is best to do this in a dedicated conda/virtual environment).
+
+   .. code-block:: shell
+
+      pushd docs
+      make html
+      popd
+
+.. note::
+
+   Note that building the documentation may fail if your build of pyarrow is
+   not sufficiently comprehensive. Portions of the Python API documentation
+   will also not build without CUDA support having been built.
+
+After these steps are completed, the documentation is rendered in HTML
+format in ``docs/_build/html``.  In particular, you can point your browser
+at ``docs/_build/html/index.html`` to read the docs and review any changes
+you made.
+
+Building with Docker
+--------------------
+
+You can use :ref:`Archery <archery>` to build the documentation within a
+Docker container.
+
+.. code-block:: shell
+
+  archery docker run ubuntu-docs
+
+The final output is located under ``docs/_build/html``.
+
+.. seealso::
+
+   :ref:`docker-builds`.