[arrow] branch master updated: ARROW-4332: [Website] Improve documentation for publishing site

[we...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

wesm 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 afb6752  ARROW-4332: [Website] Improve documentation for publishing site
afb6752 is described below

commit afb67525bf0c3c367b8267979b0f4b09a3f6feeb
Author: Andy Grove <an...@gmail.com>
AuthorDate: Sun Jan 27 11:00:24 2019 -0600

    ARROW-4332: [Website] Improve documentation for publishing site
    
    Author: Andy Grove <an...@gmail.com>
    Author: Wes McKinney <we...@apache.org>
    Author: Krisztián Szűcs <sz...@gmail.com>
    
    Closes #3498 from andygrove/ARROW-4332 and squashes the following commits:
    
    350fabdf <Wes McKinney> md formatting
    07250eb6 <Andy Grove> remove duplicate instruction
    54403799 <Andy Grove> Improve documentation for publishing the site
    39929d7a <Andy Grove> Merge remote-tracking branch 'upstream/master'
    17ee1596 <Andy Grove> Merge remote-tracking branch 'upstream/master'
    88267899 <Krisztián Szűcs> ARROW-4273:  Fix verification script to use cf201901 conda-forge label
---
 site/README.md | 43 ++++++++++++++++++++++++++++++++-----------
 1 file changed, 32 insertions(+), 11 deletions(-)

diff --git a/site/README.md b/site/README.md
index 412051c..7a287ec 100644
--- a/site/README.md
+++ b/site/README.md
@@ -17,32 +17,53 @@
   under the License.
 -->
 
-## Apache Arrow Website
+# Apache Arrow Website
 
-### Development instructions
+## Overview
 
-If you are planning to publish the website, you must first clone the arrow-site
-git repository:
+Site content is maintained in the main Arrow repository, mostly in markdown
+format. [Jekyll](https://jekyllrb.com/) is used to generate HTML files that can
+then be committed to the [arrow-site](https://github.com/apache/arrow-site)
+repository.
 
-```shell
-git clone --branch=asf-site https://github.com/apache/arrow-site.git asf-site
-```
+## Prerequisites
 
-Now, with Ruby >= 2.1 installed, run:
+With Ruby >= 2.1 installed, run the following commands to install
+[Jekyll](https://jekyllrb.com/).
 
 ```shell
 gem install jekyll bundler
 bundle install
+```
 
-# This imports the format Markdown documents so they will be rendered
+If you are planning to publish the website, you must clone the arrow-site git
+repository. Run this command from the `site` directory so that `asf-site` is a
+subdirectory of `site`.
+
+```shell
+git clone --branch=asf-site https://github.com/apache/arrow-site.git asf-site
+```
+
+Also, from the `site` directory, run the following command to import the format
+markdown documents so that they will rendered.
+
+```
 scripts/sync_format_docs.sh
+```
 
+## Previewing the site
+
+From the `site` directory, run the following to generate HTML files and run the
+web site locally.
+
+```
 bundle exec jekyll serve
 ```
 
-### Publishing
+## Publishing
 
-After following the above instructions the base `site/` directory, run:
+After following the above instructions, run the following commands from the
+`site` directory:
 
 ```shell
 JEKYLL_ENV=production bundle exec jekyll build