[arrow] branch master updated: ARROW-13379: [Dev][Docs] Improvements to archery docs

[ap...@apache.org]

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 1229858  ARROW-13379: [Dev][Docs] Improvements to archery docs
1229858 is described below

commit 122985841dcedd13bee5388cf5cb887f75cb4527
Author: Jonathan Keane <jk...@gmail.com>
AuthorDate: Mon Aug 2 16:39:50 2021 +0200

    ARROW-13379: [Dev][Docs] Improvements to archery docs
    
    Closes #10830 from jonkeane/ARROW-13379-archery-docs
    
    Lead-authored-by: Jonathan Keane <jk...@gmail.com>
    Co-authored-by: Antoine Pitrou <an...@python.org>
    Signed-off-by: Antoine Pitrou <an...@python.org>
---
 dev/archery/README.md               | 49 +++++++++++++++++++++++++++++++++++++
 docs/source/developers/archery.rst  |  4 ++-
 docs/source/developers/crossbow.rst |  9 +++++--
 3 files changed, 59 insertions(+), 3 deletions(-)

diff --git a/dev/archery/README.md b/dev/archery/README.md
new file mode 100644
index 0000000..eff6544
--- /dev/null
+++ b/dev/archery/README.md
@@ -0,0 +1,49 @@
+<!--
+  ~ 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.
+  -->
+
+# Developing with Archery
+
+Archery is documented on the Arrow website:
+
+* [Daily development using Archery](https://arrow.apache.org/docs/developers/archery.html)
+* [Using Archery and Crossbow](https://arrow.apache.org/docs/developers/crossbow.html)
+* [Using Archer and Docker](https://arrow.apache.org/docs/developers/docker.html)
+
+# Installing Archery
+
+See the pages linked aboved for more details. As a general overview, Archery
+comes in a number of subpackages, each needing to be installed if you want
+to use the functionality of it:
+
+* lint – lint (and in some cases auto-format) code in the Arrow repo
+  To install: `pip install -e "arrow/dev/archery[lint]"`
+* benchmark – to run Arrow benchmarks using Archery
+  To install: `pip install -e "arrow/dev/archery[benchmark]"`
+* docker – to run docker-compose based tasks more easily
+  To install: `pip install -e "arrow/dev/archery[docker]"`
+* release – release related helpers
+  To install: `pip install -e "arrow/dev/archery[release]"`
+* crossbow – to trigger + interact with the crossbow build system
+  To install: `pip install -e "arrow/dev/archery[crossbow]"`
+* crossbow-upload
+  To install: `pip install -e "arrow/dev/archery[crossbow-upload]"`
+
+Additionally, if you would prefer to install everything at once,
+`pip install -e "arrow/dev/archery[all]"` is an alias for all of
+the above subpackages.
\ No newline at end of file
diff --git a/docs/source/developers/archery.rst b/docs/source/developers/archery.rst
index c5a508d..f929bb2 100644
--- a/docs/source/developers/archery.rst
+++ b/docs/source/developers/archery.rst
@@ -57,10 +57,13 @@ You can inspect Archery usage by passing the ``--help`` flag:
    Commands:
      benchmark    Arrow benchmarking.
      build        Initialize an Arrow C++ build
+     crossbow     Schedule packaging tasks or nightly builds on CI services.
      docker       Interact with docker-compose based builds.
      integration  Execute protocol and Flight integration tests
+     linking      Quick and dirty utilities for checking library linkage.
      lint         Check Arrow source tree for errors
      numpydoc     Lint python docstring with NumpyDoc
+     release      Release releated commands.
      trigger-bot
 
 Archery exposes independent subcommands, each of which provides dedicated
@@ -81,4 +84,3 @@ help output, for example:
      images  List the available docker-compose images.
      push    Push the generated docker-compose image.
      run     Execute docker-compose builds.
-
diff --git a/docs/source/developers/crossbow.rst b/docs/source/developers/crossbow.rst
index 0583032..cb49a24 100644
--- a/docs/source/developers/crossbow.rst
+++ b/docs/source/developers/crossbow.rst
@@ -71,6 +71,10 @@ Install
 The following guide depends on GitHub, but theoretically any git
 server can be used.
 
+If you are not using the `ursacomputing/crossbow <https://github.com/ursacomputing/crossbow>`_
+repository, you will need to complete the first two steps, otherwise procede
+to step 3:
+
 1. `Create the queue repository`_
 
 2. Enable `TravisCI`_, `Appveyor`_, `Azure Pipelines`_ and `CircleCI`_
@@ -78,7 +82,8 @@ server can be used.
 
    -  turn off Travis’ `auto cancellation`_ feature on branches
 
-3. Clone the newly created repository next to the arrow repository:
+3. Clone either ursacomputing/crossbow if you are using that, or the newly
+   created repository next to the arrow repository:
 
    By default the scripts looks for ``crossbow`` next to arrow repository, but
    this can configured through command line arguments.
@@ -127,7 +132,7 @@ server can be used.
 
    .. code:: bash
 
-      pip install -e arrow/dev/archery[crossbow]
+      pip install -e "arrow/dev/archery[crossbow]"
 
 9. Try running it: