You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@arrow.apache.org by ap...@apache.org on 2018/12/19 14:52:32 UTC
[arrow] branch master updated: ARROW-4066: [Doc] Instructions to
create Sphinx documentation
This is an automated email from the ASF dual-hosted git repository.
apitrou pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/master by this push:
new cec8d23 ARROW-4066: [Doc] Instructions to create Sphinx documentation
cec8d23 is described below
commit cec8d23dd48e764064adcfdfb33b13989fd3b667
Author: cav71 <a....@cavallinux.eu>
AuthorDate: Wed Dec 19 15:52:23 2018 +0100
ARROW-4066: [Doc] Instructions to create Sphinx documentation
Document how to build the documentation in the Python docs.
Author: cav71 <a....@cavallinux.eu>
Author: Antoine Pitrou <an...@python.org>
Closes #3198 from cav71/documentation and squashes the following commits:
9af13754 <Antoine Pitrou> Missing word
1389e19d <Antoine Pitrou> Remove spurious newlines
61b32356 <Antoine Pitrou> Some improvements
e21fdd7a <cav71> update documentation
5ce1cf45 <cav71> update documentation
e5e6c4de <cav71> Merge remote-tracking branch 'upstream/master' into documentation
c132dffe <cav71> update doc following comments from: https://github.com/apache/arrow/pull/3198
f3620520 <cav71> doc doc
---
docs/source/python/development.rst | 59 ++++++++++++++++++++++++++++++++++++--
docs/source/python/index.rst | 17 +++++------
docs/source/python/install.rst | 4 +--
3 files changed, 68 insertions(+), 12 deletions(-)
diff --git a/docs/source/python/development.rst b/docs/source/python/development.rst
index 4258fee..1dcfda8 100644
--- a/docs/source/python/development.rst
+++ b/docs/source/python/development.rst
@@ -86,6 +86,8 @@ On Linux and OSX:
--file arrow/ci/conda_env_python.yml \
python=3.6
+ source activate pyarrow-dev
+
On Windows:
.. code-block:: shell
@@ -95,16 +97,18 @@ On Windows:
--file arrow\ci\conda_env_python.yml ^
python=3.6
+ activate pyarrow-dev
+
We need to set some environment variables to let Arrow's build system know
about our build toolchain:
.. code-block:: shell
export ARROW_BUILD_TYPE=release
-
export ARROW_BUILD_TOOLCHAIN=$CONDA_PREFIX
export ARROW_HOME=$CONDA_PREFIX
export PARQUET_HOME=$CONDA_PREFIX
+ export BOOST_HOME=$CONDA_PREFIX
Using pip
~~~~~~~~~
@@ -207,9 +211,10 @@ Now, build pyarrow:
.. code-block:: shell
- cd arrow/python
+ pushd arrow/python
python setup.py build_ext --build-type=$ARROW_BUILD_TYPE \
--with-parquet --with-plasma --inplace
+ popd
If you did not build with plasma, you can omit ``--with-plasma``.
@@ -352,3 +357,53 @@ Getting ``python-test.exe`` to run is a bit tricky because your
set PYTHONHOME=%CONDA_PREFIX%
Now ``python-test.exe`` or simply ``ctest`` (to run all tests) should work.
+
+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.yml
+
+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
+--------
+
+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
+
+ .. code-block:: shell
+
+ pushd docs
+ make html
+ popd
+
+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.
diff --git a/docs/source/python/index.rst b/docs/source/python/index.rst
index 5628219..cf691e3 100644
--- a/docs/source/python/index.rst
+++ b/docs/source/python/index.rst
@@ -18,21 +18,22 @@
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
+on the Arrow format and other language bindings see the
+:doc:`parent documentation <../index>`.
+
+The Arrow Python bindings (also named "PyArrow") have first-class integration
+with NumPy, pandas, and built-in Python objects. They are based on the C++
+implementation of Arrow.
+
+Here will we 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
@@ -44,5 +45,5 @@ files into Arrow structures.
parquet
extending
api
+ development
getting_involved
-
diff --git a/docs/source/python/install.rst b/docs/source/python/install.rst
index d07d900..8092b6c 100644
--- a/docs/source/python/install.rst
+++ b/docs/source/python/install.rst
@@ -15,8 +15,8 @@
.. specific language governing permissions and limitations
.. under the License.
-Install PyArrow
-===============
+Installing PyArrow
+==================
Conda
-----