You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@impala.apache.org by mi...@apache.org on 2017/04/05 20:22:50 UTC
incubator-impala git commit: IMPALA-5140: improve docs building
guidelines
Repository: incubator-impala
Updated Branches:
refs/heads/master 676a88f34 -> 75cca8a90
IMPALA-5140: improve docs building guidelines
Move docs/generatingImpalaDoc.md to docs/README.md. This will
automatically render the document inline at places like:
https://github.com/apache/incubator-impala/tree/master/docs
under the directory listing.
Fix existing markdown which wasn't always rendering properly. Remove
unneeded HTML and backslashes. Add a mention of make, and add one
troubleshooting tip. Wrap most lines at 90 chars. This does not change
how Github renders the markdown, and it makes reading the source easier
as well.
Explain how to get dita into PATH.
Emphasize make and remove some of the dita advanced usage.
Change-Id: I71ae79ecd346045697fe225140ee9a317c5a337f
Reviewed-on: http://gerrit.cloudera.org:8080/6512
Reviewed-by: Jim Apple <jb...@apache.org>
Tested-by: Michael Brown <mi...@cloudera.com>
Project: http://git-wip-us.apache.org/repos/asf/incubator-impala/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-impala/commit/75cca8a9
Tree: http://git-wip-us.apache.org/repos/asf/incubator-impala/tree/75cca8a9
Diff: http://git-wip-us.apache.org/repos/asf/incubator-impala/diff/75cca8a9
Branch: refs/heads/master
Commit: 75cca8a90b05b733653e31fe0791791c5616d78e
Parents: 676a88f
Author: Michael Brown <mi...@cloudera.com>
Authored: Tue Mar 21 13:10:51 2017 -0700
Committer: Michael Brown <mi...@cloudera.com>
Committed: Wed Apr 5 20:02:09 2017 +0000
----------------------------------------------------------------------
docs/README.md | 204 +++++++++++++++++++++++++++++++++++++++
docs/generatingImpalaDoc.md | 73 --------------
2 files changed, 204 insertions(+), 73 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-impala/blob/75cca8a9/docs/README.md
----------------------------------------------------------------------
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..58d4ef2
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,204 @@
+# Generating HTML or a PDF of Apache Impala (Incubating) Documentation
+
+## Prerequisites
+
+Make sure that you have a recent version of a Java JDK installed and that your
+JAVA_HOME environment variable is set. This procedure has been tested with JDK
+1.8.0. See [Setting JAVA_HOME](#setting-java_home) at the end of these
+instructions.
+
+## Download Docs Source
+
+* Open a terminal window and run the following commands to get the Impala
+ documentation source files from Git:
+ ```
+ git clone https://git-wip-us.apache.org/repos/asf/incubator-impala.git/docs
+ cd <local_directory>
+ git checkout master
+ ```
+
+ Where `master` is the branch where Impala documentation source files
+ are uploaded.
+
+## Download DITA Open Toolkit
+
+* Download the DITA Open Toolkit version 2.3.3 from the DITA Open Toolkit web site:
+
+ [https://github.com/dita-ot/dita-ot/releases/download/2.3.3/dita-ot-2.3.3.zip](https://github.com/dita-ot/dita-ot/releases/download/2.3.3/dita-ot-2.3.3.zip)
+
+ **Note:** A DITA-OT 2.3.3 User Guide is included in the toolkit. Look
+ for `userguide.pdf` in the `doc` directory of the toolkit after you
+ extract it. For example, if you extract the toolkit package to the
+ `/Users/<username>/DITA-OT` directory on Mac OS, you will find the
+ `userguide.pdf` at the following location:
+
+ ```
+ /Users/<username>/DITA-OT/doc/userguide.pdf
+ ```
+
+## Add dita Executable to Your PATH
+
+1. Identify the directory into which you extracted DITA-OT. For this
+ exercise, we'll assume it's `/Users/<username>/DITA-OT`
+2. Find your `.bash_profile`. On Mac OS X, it is probably
+ `/Users/<username>/.bash_profile`.
+3. Edit your `<path_to_bash_profile>/.bash_profile` file and add the
+ following lines to the end of the file.
+ ```
+ # Add dita to path
+ export PATH="/Users/<username>/DITA-OT/bin:$PATH"
+ ```
+ Save the file.
+4. Open a new terminal, or run `source <path_to_bash_profile>/.bash_profile`.
+5. Verify `dita` is in your `PATH`. A command like `which dita` should
+ print the location of the `dita` executable, like:
+ ```
+ $ which dita
+ /Users/<username>/DITA-OT/bin/dita
+ ```
+
+## Verify dita Executable Can Run
+
+In a terminal, try `dita --help`. You should get brief usage, like:
+ ```
+ Usage: dita -i <file> -f <name> [options]
+ or: dita -install [<file>]
+ or: dita -uninstall <id>
+ or: dita -help
+ or: dita -version
+ Arguments:
+ -i, -input <file> input file
+ -f, -format <name> output format (transformation type)
+ -install [<file>] install plug-in from a ZIP file or reload plugins
+ -uninstall <id> uninstall plug-in with the ID
+ -h, -help print this message
+ -version print version information and exit
+ Options:
+ -o, -output <dir> output directory
+ -filter <file> filter and flagging file
+ -t, -temp <dir> temporary directory
+ -v, -verbose verbose logging
+ -d, -debug print debugging information
+ -l, logfile <file> use given file for log
+ -D<property>=<value> use value for given property
+ -propertyfile <name> load all properties from file with -D
+ properties taking precedence
+ ```
+
+If you don't get this, or you get an error, see [Setting
+JAVA_HOME](#setting-java_home) and [Troubleshooting](#troubleshooting)
+at the end of these instructions.
+
+## Oneshot Docs Build
+
+The easiest way to build the docs is to run `make` from the `docs/`
+directory corresponding to your `git clone`. It takes about 1 minute.
+This works because the `make` uses the provided `Makefile` to call
+`dita` properly.
+
+Docs will end up in `docs/build` (both HTML and PDF).
+
+## Details, Advanced Usage
+
+1. In the directory where you cloned the Impala documentation files, you
+ will find the following important configuration files in the `docs`
+ subdirectory. These files are used to convert the XML source you
+ downloaded from the Apache site to PDF and HTML:
+ * `impala.ditamap`: Tells the DITA Open Toolkit what topics to
+ include in the Impala User/Administration Guide. This guide also
+ includes the Impala SQL Reference.
+ * `impala_sqlref.ditamap`: Tells the DITA Open Toolkit what topics
+ to include in the Impala SQL Reference.
+ * `impala_html.ditaval`: Further defines what topics to include in
+ the Impala HTML output.
+ * `impala_pdf.ditaval`: Further defines what topics to include in
+ the Impala PDF output.
+2. Run one of the following commands, depending on what you want to
+ generate:
+ * **To generate HTML output of the Impala User and Administration
+ Guide, which includes the Impala SQL Reference, run the following
+ command:**
+ ```
+ dita -input <path_to_impala.ditamap> -format html5 \
+ -output <path_to_build_output_directory> \
+ -filter <path_to_impala_html.ditaval>
+ ```
+
+ * **To generate PDF output of the Impala User and Administration
+ Guide, which includes the Impala SQL Reference, run the following
+ command:**
+
+ ```
+ dita -input <path_to_impala.ditamap> -format pdf \
+ -output <path_to_build_output_directory> \
+ -filter <path_to_impala_pdf.ditaval>
+ ```
+
+ **Note:** For a description of all command-line options, see the
+ _DITA Open Toolkit User Guide_ in the `doc` directory of your
+ downloaded DITA Open Toolkit.
+
+# Setting JAVA_HOME
+
+Set your JAVA_HOME environment variable to tell your computer where to
+find the Java executable file. For example, to set your JAVA_HOME
+environment on Mac OS X when you have the 1.8.0_101 version of the Java
+Development Kit (JDK) installed and you are using the Bash version 3.2
+shell, perform the following steps:
+
+1. Find your `.bash_profile`. On Mac OS X, it is probably
+ `/Users/<username>/.bash_profile`. Edit your
+ `<path_to_bash_profile>/.bash_profile` file and add the following
+ lines to the end of the file.
+ ```
+ # Set JAVA_HOME
+ JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.8.0_101.jdk/Contents/Home
+ export JAVA_HOME
+ ```
+
+ Where `jdk1.8.0_101.jdk` is the version of JDK that you have
+ installed. For example, if you have installed `jdk1.8.0_102.jdk`, you
+ would use that value instead.
+
+2. Open a new terminal, or run `source <path_to_bash_profile>/.bash_profile`.
+3. Test to make sure you have set your JAVA_HOME correctly:
+ * Open a terminal window and type: `$JAVA_HOME/bin/java -version`
+ * Press return. If you see something like the following:
+ ```
+ java version "1.8.0_101"
+ Java(TM) 2 Runtime Environment, Standard Edition (build 1.8.0_101-b06-284)
+ Java HotSpot (TM) Client VM (build 1.8.0_101-133, mixed mode, sharing)
+ ```
+
+ Then you've successfully set your JAVA_HOME environment variable
+ to the binary stored in
+ `/Library/Java/JavaVirtualMachines/jdk1.8.0_101.jdk/Contents/Home`.
+
+ **Note:** The exact version and build number on your system may
+ differ. The point is you want a message like the above.
+
+# Troubleshooting
+
+## Ant
+
+If you're trying to use DITA-OT to build docs and you get an exception like this
+```
+java.lang.NoSuchMethodError: org.apache.tools.ant.Main: method <init>()V not found
+ at org.dita.dost.invoker.Main.<init>(Main.java:418)
+ at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
+ at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:57)
+ at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)
+ at java.lang.reflect.Constructor.newInstance(Constructor.java:526)
+ at java.lang.Class.newInstance(Class.java:379)
+ at org.apache.tools.ant.launch.Launcher.run(Launcher.java:279)
+ at org.apache.tools.ant.launch.Launcher.main(Launcher.java:109)
+```
+
+... your `CLASSPATH` may be interfering with DITA-OT's ability to find
+the proper Ant. While you're free to fix the `CLASSPATH` yourself, it
+may be easier just to run
+
+`unset CLASSPATH`
+
+and try again. This will use the libraries and Ant provided by the
+DITA-OT package.
http://git-wip-us.apache.org/repos/asf/incubator-impala/blob/75cca8a9/docs/generatingImpalaDoc.md
----------------------------------------------------------------------
diff --git a/docs/generatingImpalaDoc.md b/docs/generatingImpalaDoc.md
deleted file mode 100644
index 5021e39..0000000
--- a/docs/generatingImpalaDoc.md
+++ /dev/null
@@ -1,73 +0,0 @@
-#Generating HTML or a PDF of Apache Impala (Incubating) Documentation
-
-##Prerequisites:
-Make sure that you have a recent version of a Java JDK installed and that your JAVA\_HOME environment variable is set. This procedure has been tested with JDK 1.8.0. See [Setting JAVA\_HOME](#settingjavahome) at the end of these instructions.
-
-* Open a terminal window and run the following commands to get the Impala documentation source files from Git:
-
- <pre><code>git clone https://git-wip-us.apache.org/repos/asf/incubator-impala.git/docs
- cd \<local\_directory\>
- git checkout doc\_prototype</code></pre>
-
- Where <code>doc\_prototype</code> is the branch where Impala documentation source files are uploaded.
-
-* Download the DITA Open Toolkit version 2.3.3 from the DITA Open Toolkit web site:
-
- [https://github.com/dita-ot/dita-ot/releases/download/2.3.3/dita-ot-2.3.3.zip] (https://github.com/dita-ot/dita-ot/releases/download/2.3.3/dita-ot-2.3.3.zip)
-
- **Note:** A DITA-OT 2.3.3 User Guide is included in the toolkit. Look for <code>userguide.pdf</code> in the <code>doc</code> directory of the toolkit after you extract it. For example, if you extract the toolkit package to the <code>/Users/\<_username_\>/DITA-OT</code> directory on Mac OS, you will find the <code>userguide.pdf</code> at the following location:
-
- <code>/Users/\<_username_\>/DITA-OT/doc/userguide.pdf</code>
-
-##To generate HTML or PDF:
-
-1. In the directory where you cloned the Impala documentation files, you will find the following important configuration files in the <code>docs</code> subdirectory. These files are used to convert the XML source you downloaded from the Apache site to PDF and HTML:
- * <code>impala.ditamap</code>: Tells the DITA Open Toolkit what topics to include in the Impala User/Administration Guide. This guide also includes the Impala SQL Reference.
- * <code>impala\_sqlref.ditamap</code>: Tells the DITA Open Toolkit what topics to include in the Impala SQL Reference.
- * <code>impala\_html.ditaval</code>: Further defines what topics to include in the Impala HTML output.
- * <code>impala\_pdf.ditaval</code>: Further defines what topics to include in the Impala PDF output.
-2. Extract the contents of the DITA-OT package into a directory where you want to generate the HTML or the PDF.
-3. Open a terminal window and navigate to the directory where you extracted the DITA-OT package.
-4. Run one of the following commands, depending on what you want to generate:
- * **To generate HTML output of the Impala User and Administration Guide, which includes the Impala SQL Reference, run the following command:**
-
- <code>./bin/dita -input \<path\_to\_impala.ditamap\> -format html5 -output \<path\_to\_build\_output\_directory\> -filter \<path\_to\_impala\_html.ditaval\></code>
-
- * **To generate PDF output of the Impala User and Administration Guide, which includes the Impala SQL Reference, run the following command:**
-
- <code>./bin/dita -input \<path\_to\_impala.ditamap\> -format pdf -output \<path\_to\_build\_output\_directory\> -filter \<path\_to\_impala\_pdf.ditaval\></code>
-
- * **To generate HTML output of the Impala SQL Reference, run the following command:**
-
- <code>./bin/dita -input \<path\_to\_impala\_sqlref.ditamap\> -format html5 -output \<path\_to\_build\_output\_directory\> -filter \<path\_to\_impala\_html.ditaval\></code>
-
- * **To generate PDF output of the Impala SQL Reference, run the following command:**
-
- <code>./bin/dita -input \<path\_to\_impala\_sqlref.ditamap\> -format pdf -output \<path\_to\_build\_output\_directory\> -filter \<path\_to\_impala\_pdf.ditaval\></code>
-
- **Note:** For a description of all command-line options, see the _DITA Open Toolkit User Guide_ in the <code>doc</code> directory of your downloaded DITA Open Toolkit.
-
-5. Go to the output directory that you specified in Step 3 to view the HTML or PDF that you generated. If you generated HTML, open the <code>index.html</code> file with a browser to view the output.
-
-<a name="settingjavahome" />
-#Setting JAVA\_HOME
-</a>
-
-Set your JAVA\_HOME environment variable to tell your computer where to find the Java executable file. For example, to set your JAVA\_HOME environment on Mac OS X when you the the 1.8.0\_101 version of the Java Development Kit (JDK) installed and you are using the Bash version 3.2 shell, perform the following steps:
-
-1. Edit your <code>/Users/\<username\>/.bash\_profile</code> file and add the following lines to the end of the file:
-
- <pre><code>#Set JAVA_HOME
- JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.8.0_101.jdk/Contents/Home
- export JAVA_HOME;</code></pre>
-
- Where <code>jdk1.8.0\_101.jdk</code> is the version of JDK that you have installed. For example, if you have installed <code>jdk1.8.0\_102.jdk</code>, you would use that value instead.
-
-2. Test to make sure you have set your JAVA\_HOME correctly:
- * Open a terminal window and type: <code>$JAVA\_HOME/bin/java -version</code>
- * Press return. If you see something like the following:
- <pre><code>java version "1.5.0_16"
- Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_16-b06-284)
- Java HotSpot (TM) Client VM (build 1.5.0\_16-133, mixed mode, sharing)</code></pre>
-
- Then you've successfully set your JAVA\_HOME environment variable to the binary stored in <code>/Library/Java/JavaVirtualMachines/jdk1.8.0\_101.jdk/Contents/Home</code>.
\ No newline at end of file