You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@kudu.apache.org by jd...@apache.org on 2017/04/04 21:56:04 UTC
[2/4] kudu git commit: docs: Add a section for evolving gflags
docs: Add a section for evolving gflags
This patch adds a new section for evolving gflags in the documentation
and changes some of the XSLT logic to be more consistent.
It would be nice to replace the XSLT with a Python script.
Change-Id: I791d91e4f7ace4483958d26a60817857899fb474
Reviewed-on: http://gerrit.cloudera.org:8080/6489
Tested-by: Kudu Jenkins
Reviewed-by: Will Berkeley <wd...@gmail.com>
(cherry picked from commit 824b0f46dc3d1443ad10db1b07cb085cb5bd7a4e)
Reviewed-on: http://gerrit.cloudera.org:8080/6546
Reviewed-by: Jean-Daniel Cryans <jd...@apache.org>
Project: http://git-wip-us.apache.org/repos/asf/kudu/repo
Commit: http://git-wip-us.apache.org/repos/asf/kudu/commit/764b6c24
Tree: http://git-wip-us.apache.org/repos/asf/kudu/tree/764b6c24
Diff: http://git-wip-us.apache.org/repos/asf/kudu/diff/764b6c24
Branch: refs/heads/branch-1.3.x
Commit: 764b6c244f99ad5b4122b8b405802b5488da368e
Parents: ae25d1c
Author: Mike Percy <mp...@apache.org>
Authored: Fri Mar 24 19:27:21 2017 -0700
Committer: Jean-Daniel Cryans <jd...@apache.org>
Committed: Tue Apr 4 21:44:43 2017 +0000
----------------------------------------------------------------------
docs/configuration_reference.adoc | 6 +-
docs/configuration_reference_unsupported.adoc | 8 +--
docs/support/scripts/make_docs.sh | 4 +-
docs/support/xsl/gflags_to_asciidoc.xsl | 66 ++++++++++++++++++----
4 files changed, 64 insertions(+), 20 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/kudu/blob/764b6c24/docs/configuration_reference.adoc
----------------------------------------------------------------------
diff --git a/docs/configuration_reference.adoc b/docs/configuration_reference.adoc
index 630b0a5..eedc23a 100644
--- a/docs/configuration_reference.adoc
+++ b/docs/configuration_reference.adoc
@@ -28,9 +28,9 @@
:sectlinks:
:experimental:
-The contents of this file are generated from the output of the `--helpxml`
-flag for each binary, during the build of the documentation. Do not edit this file
-or the included files manually.
+// The contents of this file are generated from the output of the `--helpxml`
+// flag for each binary, during the build of the documentation. Do not edit
+// this file or the included files manually.
// This gets replaced by the script that builds the docs
@@CONFIGURATION_REFERENCE@@
http://git-wip-us.apache.org/repos/asf/kudu/blob/764b6c24/docs/configuration_reference_unsupported.adoc
----------------------------------------------------------------------
diff --git a/docs/configuration_reference_unsupported.adoc b/docs/configuration_reference_unsupported.adoc
index 20d0ecb..cbfd70f 100644
--- a/docs/configuration_reference_unsupported.adoc
+++ b/docs/configuration_reference_unsupported.adoc
@@ -27,12 +27,12 @@
:sectlinks:
:experimental:
-The contents of this file are generated from the output of the `--helpxml`
-flag for each binary, during the build of the documentation. Do not edit this file
-or the included files manually.
+// The contents of this file are generated from the output of the `--helpxml`
+// flag for each binary, during the build of the documentation. Do not edit
+// this file or the included files manually.
WARNING: These flags are unsupported and are included for informational purposes only.
-They are subject to change or be removed at any time.
+They are subject to being changed or removed at any time.
// This gets replaced by the script that builds the docs
@@CONFIGURATION_REFERENCE@@
http://git-wip-us.apache.org/repos/asf/kudu/blob/764b6c24/docs/support/scripts/make_docs.sh
----------------------------------------------------------------------
diff --git a/docs/support/scripts/make_docs.sh b/docs/support/scripts/make_docs.sh
index 8c94804..dcbc1f8 100755
--- a/docs/support/scripts/make_docs.sh
+++ b/docs/support/scripts/make_docs.sh
@@ -146,7 +146,7 @@ for binary in ${binaries[@]}; do
# Create the supported config reference
xsltproc \
--stringparam binary $binary \
- --stringparam support-level stable \
+ --stringparam support-level supported \
-o $GEN_DOC_DIR/${binary}_configuration_reference.adoc \
$SOURCE_ROOT/docs/support/xsl/gflags_to_asciidoc.xsl \
${GEN_DOC_DIR}/$binary.xml
@@ -184,7 +184,7 @@ cp $SOURCE_ROOT/docs/images/* "$OUTPUT_DIR/images/"
echo
echo ----------------------------
-echo "Docs built in $OUTPUT_DIR."
+echo "Docs built in $OUTPUT_DIR"
# If we're building the site, try to run Jekyll for them to make
# it a bit easier to quickly preview the results.
http://git-wip-us.apache.org/repos/asf/kudu/blob/764b6c24/docs/support/xsl/gflags_to_asciidoc.xsl
----------------------------------------------------------------------
diff --git a/docs/support/xsl/gflags_to_asciidoc.xsl b/docs/support/xsl/gflags_to_asciidoc.xsl
index ef79f88..a730251 100644
--- a/docs/support/xsl/gflags_to_asciidoc.xsl
+++ b/docs/support/xsl/gflags_to_asciidoc.xsl
@@ -59,16 +59,22 @@ limitations under the License.
:sectlinks:
:experimental:
-<xsl:if test="$support-level = 'stable'">
-[[<xsl:value-of select="$binary"/>_stable]]
+<!--start supported -->
+<xsl:if test="$support-level = 'supported'">
+[[<xsl:value-of select="$binary"/>_supported]]
= `<xsl:value-of select="$binary"/>` Flags
+[[<xsl:value-of select="$binary"/>_stable]]
== Stable Flags
Flags tagged `stable` and not `advanced` are safe to use for common
configuration tasks.
-<xsl:for-each select="flag"><xsl:if test="contains(tags, 'stable') and not(contains(tags, 'advanced')) and not(contains(tags, 'hidden'))">
+<xsl:for-each select="flag">
+ <xsl:if test="contains(tags, 'stable') and
+ not(contains(tags, 'advanced')) and
+ not(contains(tags, 'hidden')) and
+ not(contains(tags, 'unsafe'))">
[[<xsl:value-of select="$binary"/>_<xsl:value-of select="name"/>]]
=== `--<xsl:value-of select="name"/>`
@@ -82,7 +88,7 @@ configuration tasks.
|===
{nbsp}
-</xsl:if>
+ </xsl:if>
</xsl:for-each>
@@ -92,7 +98,11 @@ configuration tasks.
Flags tagged `stable` and `advanced` are supported, but should be considered
"expert" options and should be used carefully and after thorough testing.
-<xsl:for-each select="flag"><xsl:if test="contains(tags, 'stable') and contains(tags, 'advanced') and not(contains(tags, 'hidden'))">
+<xsl:for-each select="flag">
+ <xsl:if test="contains(tags, 'stable') and
+ contains(tags, 'advanced') and
+ not(contains(tags, 'hidden')) and
+ not(contains(tags, 'unsafe'))">
[[<xsl:value-of select="$binary"/>_<xsl:value-of select="name"/>]]
=== `--<xsl:value-of select="name"/>`
@@ -106,21 +116,55 @@ Flags tagged `stable` and `advanced` are supported, but should be considered
|===
{nbsp}
-</xsl:if>
+ </xsl:if>
</xsl:for-each>
+
+[[<xsl:value-of select="$binary"/>_evolving]]
+== Evolving Flags
+
+Flags tagged `evolving` (or not tagged with a stability tag) are not yet
+considered final, and while they may be useful for tuning, they are subject to
+being changed or removed without notice.
+
+<xsl:for-each select="flag">
+ <xsl:if test="not(contains(tags, 'stable')) and
+ not(contains(tags, 'experimental')) and
+ not(contains(tags, 'hidden')) and
+ not(contains(tags, 'unsafe'))">
+[[<xsl:value-of select="$binary"/>_<xsl:value-of select="name"/>]]
+=== `--<xsl:value-of select="name"/>`
+
+<xsl:value-of select="meaning"/>
+
+[cols="1h,3d", width="50%"]
+|===
+| Type | <xsl:value-of select="type"/>
+| Default | <xsl:choose><xsl:when test="default != ''">`<xsl:value-of select="default"/>`</xsl:when><xsl:otherwise>none</xsl:otherwise></xsl:choose>
+| Tags | <xsl:value-of select="tags"/>
+|===
+{nbsp}
+
+ </xsl:if>
+</xsl:for-each>
+
'''
</xsl:if>
-<!--end stable -->
+<!--end supported -->
<!-- start unsupported -->
<xsl:if test="$support-level = 'unsupported'">
[[<xsl:value-of select="$binary"/>_unsupported]]
= `<xsl:value-of select="$binary"/>` Unsupported Flags
-Flags marked `advanced` or `experimental` and not marked `stable`, or flags with no stability tag, are *unsupported* and are included
-for informational purposes only. They are subject to change or be removed without notice.
+Flags not marked `stable` or `evolving` are considered experimental and are
+*unsupported*. They are included here for informational purposes only and are
+subject to being changed or removed without notice.
-<xsl:for-each select="flag"><xsl:if test="not(contains(tags, 'stable')) and (contains(tags, 'advanced') or contains(tags, 'experimental')) and not(contains(tags, 'hidden'))">
+<xsl:for-each select="flag">
+ <xsl:if test="not(contains(tags, 'stable')) and
+ not(contains(tags, 'evolving')) and
+ not(contains(tags, 'hidden')) and
+ not(contains(tags, 'unsafe'))">
[[<xsl:value-of select="$binary"/>_<xsl:value-of select="name"/>]]
== `--<xsl:value-of select="name"/>`
@@ -132,7 +176,7 @@ for informational purposes only. They are subject to change or be removed withou
| Default | <xsl:choose><xsl:when test="default != ''">`<xsl:value-of select="default"/>`</xsl:when><xsl:otherwise>none</xsl:otherwise></xsl:choose>
| Tags | <xsl:value-of select="tags"/>
|===
-</xsl:if>
+ </xsl:if>
</xsl:for-each>
'''
</xsl:if>