[SPARK-31636][SQL][DOCS] Remove HTML syntax in SQL reference

### What changes were proposed in this pull request? Remove the unneeded embedded inline HTML markup by using the basic markdown syntax. Please see apache#28414 ### Why are the changes needed? Make the doc cleaner and easily editable by MD editors. ### Does this PR introduce _any_ user-facing change? No ### How was this patch tested? Manually build and check Closes apache#28451 from huaxingao/html_cleanup. Authored-by: Huaxin Gao <[email protected]> Signed-off-by: Sean Owen <[email protected]>
ScrapCodes · May 10, 2020 · a75dc80 · a75dc80
1 parent ce63bef
commit a75dc80
Show file tree

Hide file tree

Showing 80 changed files with 1,979 additions and 2,506 deletions.
diff --git a/docs/_data/menu-sql.yaml b/docs/_data/menu-sql.yaml
@@ -156,22 +156,22 @@
                   url: sql-ref-syntax-qry-select-distribute-by.html
                 - text: LIMIT Clause 
                   url: sql-ref-syntax-qry-select-limit.html
+                - text: Common Table Expression
+                  url: sql-ref-syntax-qry-select-cte.html
+                - text: Inline Table
+                  url: sql-ref-syntax-qry-select-inline-table.html
                 - text: JOIN
                   url: sql-ref-syntax-qry-select-join.html
                 - text: Join Hints
                   url: sql-ref-syntax-qry-select-hints.html
+                - text: LIKE Predicate
+                  url: sql-ref-syntax-qry-select-like.html
                 - text: Set Operators
                   url: sql-ref-syntax-qry-select-setops.html
                 - text: TABLESAMPLE
                   url: sql-ref-syntax-qry-sampling.html
                 - text: Table-valued Function
                   url: sql-ref-syntax-qry-select-tvf.html
-                - text: Inline Table
-                  url: sql-ref-syntax-qry-select-inline-table.html
-                - text: Common Table Expression
-                  url: sql-ref-syntax-qry-select-cte.html
-                - text: LIKE Predicate
-                  url: sql-ref-syntax-qry-select-like.html
                 - text: Window Function
                   url: sql-ref-syntax-qry-window.html
             - text: EXPLAIN
@@ -213,20 +213,20 @@
               subitems:
                 - text: SHOW COLUMNS 
                   url: sql-ref-syntax-aux-show-columns.html
+                - text: SHOW CREATE TABLE
+                  url: sql-ref-syntax-aux-show-create-table.html
                 - text: SHOW DATABASES
                   url: sql-ref-syntax-aux-show-databases.html
                 - text: SHOW FUNCTIONS
                   url: sql-ref-syntax-aux-show-functions.html
+                - text: SHOW PARTITIONS
+                  url: sql-ref-syntax-aux-show-partitions.html
                 - text: SHOW TABLE
                   url: sql-ref-syntax-aux-show-table.html
                 - text: SHOW TABLES
                   url: sql-ref-syntax-aux-show-tables.html
                 - text: SHOW TBLPROPERTIES
                   url: sql-ref-syntax-aux-show-tblproperties.html
-                - text: SHOW PARTITIONS 
-                  url: sql-ref-syntax-aux-show-partitions.html
-                - text: SHOW CREATE TABLE
-                  url: sql-ref-syntax-aux-show-create-table.html
                 - text: SHOW VIEWS
                   url: sql-ref-syntax-aux-show-views.html
             - text: CONFIGURATION MANAGEMENT

diff --git a/docs/sql-ref-ansi-compliance.md b/docs/sql-ref-ansi-compliance.md
@@ -41,10 +41,10 @@ This means that in case an operation causes overflows, the result is the same wi
 On the other hand, Spark SQL returns null for decimal overflows.
 When `spark.sql.ansi.enabled` is set to `true` and an overflow occurs in numeric and interval arithmetic operations, it throws an arithmetic exception at runtime.
 
-{% highlight sql %}
+```sql
 -- `spark.sql.ansi.enabled=true`
 SELECT 2147483647 + 1;
-  java.lang.ArithmeticException: integer overflow
+java.lang.ArithmeticException: integer overflow
 
 -- `spark.sql.ansi.enabled=false`
 SELECT 2147483647 + 1;
@@ -53,7 +53,7 @@ SELECT 2147483647 + 1;
 +----------------+
 |     -2147483648|
 +----------------+
-{% endhighlight %}
+```
 
 ### Type Conversion
 
@@ -64,15 +64,15 @@ On the other hand, `INSERT INTO` syntax throws an analysis exception when the AN
 Currently, the ANSI mode affects explicit casting and assignment casting only.
 In future releases, the behaviour of type coercion might change along with the other two type conversion rules.
 
-{% highlight sql %}
+```sql
 -- Examples of explicit casting
 
 -- `spark.sql.ansi.enabled=true`
 SELECT CAST('a' AS INT);
-  java.lang.NumberFormatException: invalid input syntax for type numeric: a
+java.lang.NumberFormatException: invalid input syntax for type numeric: a
 
 SELECT CAST(2147483648L AS INT);
-  java.lang.ArithmeticException: Casting 2147483648 to int causes overflow
+java.lang.ArithmeticException: Casting 2147483648 to int causes overflow
 
 -- `spark.sql.ansi.enabled=false` (This is a default behaviour)
 SELECT CAST('a' AS INT);
@@ -94,8 +94,8 @@ CREATE TABLE t (v INT);
 
 -- `spark.sql.storeAssignmentPolicy=ANSI`
 INSERT INTO t VALUES ('1');
-  org.apache.spark.sql.AnalysisException: Cannot write incompatible data to table '`default`.`t`':
-  - Cannot safely cast 'v': StringType to IntegerType;
+org.apache.spark.sql.AnalysisException: Cannot write incompatible data to table '`default`.`t`':
+- Cannot safely cast 'v': StringType to IntegerType;
 
 -- `spark.sql.storeAssignmentPolicy=LEGACY` (This is a legacy behaviour until Spark 2.x)
 INSERT INTO t VALUES ('1');
@@ -105,7 +105,7 @@ SELECT * FROM t;
 +---+
 |  1|
 +---+
-{% endhighlight %}
+```
 
 ### SQL Functions
 

diff --git a/docs/sql-ref-datatypes.md b/docs/sql-ref-datatypes.md
@@ -240,7 +240,7 @@ Specifically:
 
 #### Examples
 
-{% highlight sql %}
+```sql
 SELECT double('infinity') AS col;
 +--------+
 |     col|
@@ -313,4 +313,4 @@ SELECT COUNT(*), c2 FROM test GROUP BY c2;
 |        2|-Infinity|
 |        3| Infinity|
 +---------+---------+
-{% endhighlight %}
+```
diff --git a/docs/sql-ref-functions-builtin.md b/docs/sql-ref-functions-builtin.md
@@ -70,7 +70,7 @@ license: |
 ### JSON Functions
 {% include_relative generated-json-funcs-table.html %}
 #### Examples
-{% include_relative generated-agg-funcs-examples.html %}
+{% include_relative generated-json-funcs-examples.html %}
         {% break %}
     {% endif %}
 {% endfor %}

diff --git a/docs/sql-ref-functions-udf-aggregate.md b/docs/sql-ref-functions-udf-aggregate.md
@@ -27,46 +27,35 @@ User-Defined Aggregate Functions (UDAFs) are user-programmable routines that act
 
 A base class for user-defined aggregations, which can be used in Dataset operations to take all of the elements of a group and reduce them to a single value.
 
- * IN - The input type for the aggregation.
- * BUF - The type of the intermediate value of the reduction.
- * OUT - The type of the final output result.
+  ***IN*** - The input type for the aggregation.
+
+  ***BUF*** - The type of the intermediate value of the reduction.
+
+  ***OUT*** - The type of the final output result.
+
+* **bufferEncoder: Encoder[BUF]**
 
-<dl>
-  <dt><code><em>bufferEncoder: Encoder[BUF]</em></code></dt>
-  <dd>
     Specifies the Encoder for the intermediate value type.
-  </dd>
-</dl>
-<dl>
-  <dt><code><em>finish(reduction: BUF): OUT</em></code></dt>
-  <dd>
+
+* **finish(reduction: BUF): OUT**
+
     Transform the output of the reduction.
-  </dd>
-</dl>
-<dl>
-  <dt><code><em>merge(b1: BUF, b2: BUF): BUF</em></code></dt>
-  <dd>
+
+* **merge(b1: BUF, b2: BUF): BUF**
+
     Merge two intermediate values.
-  </dd>
-</dl>
-<dl>
-  <dt><code><em>outputEncoder: Encoder[OUT]</em></code></dt>
-  <dd>
+
+* **outputEncoder: Encoder[OUT]**
+
     Specifies the Encoder for the final output value type.
-  </dd>
-</dl>
-<dl>
-  <dt><code><em>reduce(b: BUF, a: IN): BUF</em></code></dt>
-  <dd>
-     Aggregate input value <code>a</code> into current intermediate value. For performance, the function may modify <code>b</code> and return it instead of constructing new object for <code>b</code>.
-  </dd>
-</dl>
-<dl>
-  <dt><code><em>zero: BUF</em></code></dt>
-  <dd>
+
+* **reduce(b: BUF, a: IN): BUF**
+
+     Aggregate input value `a` into current intermediate value. For performance, the function may modify `b` and return it instead of constructing new object for `b`.
+
+* **zero: BUF**
+
     The initial value of the intermediate result for this aggregation.
-  </dd>
-</dl>
 
 ### Examples
 
@@ -95,16 +84,16 @@ For example, a user-defined average for untyped DataFrames can look like:
   {% include_example untyped_custom_aggregation java/org/apache/spark/examples/sql/JavaUserDefinedUntypedAggregation.java%}
 </div>
 <div data-lang="SQL"  markdown="1">
-{% highlight sql %}
+```sql
 -- Compile and place UDAF MyAverage in a JAR file called `MyAverage.jar` in /tmp.
 CREATE FUNCTION myAverage AS 'MyAverage' USING JAR '/tmp/MyAverage.jar';
 
 SHOW USER FUNCTIONS;
--- +------------------+
--- |          function|
--- +------------------+
--- | default.myAverage|
--- +------------------+
++------------------+
+|          function|
++------------------+
+| default.myAverage|
++------------------+
 
 CREATE TEMPORARY VIEW employees
 USING org.apache.spark.sql.json
@@ -113,26 +102,26 @@ OPTIONS (
 );
 
 SELECT * FROM employees;
--- +-------+------+
--- |   name|salary|
--- +-------+------+
--- |Michael|  3000|
--- |   Andy|  4500|
--- | Justin|  3500|
--- |  Berta|  4000|
--- +-------+------+
++-------+------+
+|   name|salary|
++-------+------+
+|Michael|  3000|
+|   Andy|  4500|
+| Justin|  3500|
+|  Berta|  4000|
++-------+------+
 
 SELECT myAverage(salary) as average_salary FROM employees;
--- +--------------+
--- |average_salary|
--- +--------------+
--- |        3750.0|
--- +--------------+
-{% endhighlight %}
++--------------+
+|average_salary|
++--------------+
+|        3750.0|
++--------------+
+```
 </div>
 </div>
 
 ### Related Statements
 
- * [Scalar User Defined Functions (UDFs)](sql-ref-functions-udf-scalar.html)
- * [Integration with Hive UDFs/UDAFs/UDTFs](sql-ref-functions-udf-hive.html)
+* [Scalar User Defined Functions (UDFs)](sql-ref-functions-udf-scalar.html)
+* [Integration with Hive UDFs/UDAFs/UDTFs](sql-ref-functions-udf-hive.html)
diff --git a/docs/sql-ref-functions-udf-hive.md b/docs/sql-ref-functions-udf-hive.md
@@ -28,7 +28,7 @@ Spark SQL supports integration of Hive UDFs, UDAFs and UDTFs. Similar to Spark U
 Hive has two UDF interfaces: [UDF](https://github.com/apache/hive/blob/master/udf/src/java/org/apache/hadoop/hive/ql/exec/UDF.java) and [GenericUDF](https://github.com/apache/hive/blob/master/ql/src/java/org/apache/hadoop/hive/ql/udf/generic/GenericUDF.java).
 An example below uses [GenericUDFAbs](https://github.com/apache/hive/blob/master/ql/src/java/org/apache/hadoop/hive/ql/udf/generic/GenericUDFAbs.java) derived from `GenericUDF`.
 
-{% highlight sql %}
+```sql
 -- Register `GenericUDFAbs` and use it in Spark SQL.
 -- Note that, if you use your own programmed one, you need to add a JAR containing it
 -- into a classpath,
@@ -52,12 +52,12 @@ SELECT testUDF(value) FROM t;
 |           2.0|
 |           3.0|
 +--------------+
-{% endhighlight %}
+```
 
 
 An example below uses [GenericUDTFExplode](https://github.com/apache/hive/blob/master/ql/src/java/org/apache/hadoop/hive/ql/udf/generic/GenericUDTFExplode.java) derived from [GenericUDTF](https://github.com/apache/hive/blob/master/ql/src/java/org/apache/hadoop/hive/ql/udf/generic/GenericUDF.java).
 
-{% highlight sql %}
+```sql
 -- Register `GenericUDTFExplode` and use it in Spark SQL
 CREATE TEMPORARY FUNCTION hiveUDTF
     AS 'org.apache.hadoop.hive.ql.udf.generic.GenericUDTFExplode';
@@ -79,12 +79,12 @@ SELECT hiveUDTF(value) FROM t;
 |  3|
 |  4|
 +---+
-{% endhighlight %}
+```
 
 Hive has two UDAF interfaces: [UDAF](https://github.com/apache/hive/blob/master/udf/src/java/org/apache/hadoop/hive/ql/exec/UDAF.java) and [GenericUDAFResolver](https://github.com/apache/hive/blob/master/ql/src/java/org/apache/hadoop/hive/ql/udf/generic/GenericUDAFResolver.java).
 An example below uses [GenericUDAFSum](https://github.com/apache/hive/blob/master/ql/src/java/org/apache/hadoop/hive/ql/udf/generic/GenericUDAFSum.java) derived from `GenericUDAFResolver`.
 
-{% highlight sql %}
+```sql
 -- Register `GenericUDAFSum` and use it in Spark SQL
 CREATE TEMPORARY FUNCTION hiveUDAF
     AS 'org.apache.hadoop.hive.ql.udf.generic.GenericUDAFSum';
@@ -105,4 +105,4 @@ SELECT key, hiveUDAF(value) FROM t GROUP BY key;
 |  b|              3|
 |  a|              3|
 +---+---------------+
-{% endhighlight %}
+```
diff --git a/docs/sql-ref-functions-udf-scalar.md b/docs/sql-ref-functions-udf-scalar.md
@@ -26,24 +26,18 @@ User-Defined Functions (UDFs) are user-programmable routines that act on one row
 ### UserDefinedFunction
 
 To define the properties of a user-defined function, the user can use some of the methods defined in this class.
-<dl>
-  <dt><code><em>asNonNullable(): UserDefinedFunction</em></code></dt>
-  <dd>
+
+* **asNonNullable(): UserDefinedFunction**
+
     Updates UserDefinedFunction to non-nullable.
-  </dd>
-</dl>
-<dl>
-  <dt><code><em>asNondeterministic(): UserDefinedFunction</em></code></dt>
-  <dd>
+
+* **asNondeterministic(): UserDefinedFunction**
+
     Updates UserDefinedFunction to nondeterministic.
-  </dd>
-</dl>
-<dl>
-  <dt><code><em>withName(name: String): UserDefinedFunction</em></code></dt>
-  <dd>
+
+* **withName(name: String): UserDefinedFunction**
+
     Updates UserDefinedFunction with a given name.
-  </dd>
-</dl>
 
 ### Examples
 
@@ -57,5 +51,5 @@ To define the properties of a user-defined function, the user can use some of th
 </div>
 
 ### Related Statements
- * [User Defined Aggregate Functions (UDAFs)](sql-ref-functions-udf-aggregate.html)
- * [Integration with Hive UDFs/UDAFs/UDTFs](sql-ref-functions-udf-hive.html)
+* [User Defined Aggregate Functions (UDAFs)](sql-ref-functions-udf-aggregate.html)
+* [Integration with Hive UDFs/UDAFs/UDTFs](sql-ref-functions-udf-hive.html)