[
https://issues.apache.org/jira/browse/SPARK-11337?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14981688#comment-14981688
]
Xusen Yin commented on SPARK-11337:
-----------------------------------
[~mengxr] There are another two issues when I reviewing recent two PRs.
1. The trim_codeblock(lines) function in include_example.rb removes some blank
lines in the code. I will add follow-up PR to fix it.
2. Currently, I add a blank line in two consecutive code blocks. However, the
blank line will cut off some imports which should be joined together without
any blanks. Say if we have a code which imports
// $example on$
import org.apache.spark.aaaa
// $example off$
import org.apache.spark.bbbb
// $example on$
import org.apache.spark.cccc
// $example off$
The result is
import org.apache.spark.aaaa
[blank line here]
import org.apache.spark.cccc
But we don't want the result like this. We want compact imports since they are
all belongs to org.apache.spark.*
Here are several solutions:
1. We select all imports in the example code, so there will be some unnecessary
imports appear in the document.
2. We put the necessary imports together and use one $example on$ ... $example
off$ to select them. But it may disorder the Scala style requirement though it
can pass the Scala style check.
3. We write a smart logic to check the situation and join this kind of imports
together without blank line insertion.
Which one do you prefer?
> Make example code in user guide testable
> ----------------------------------------
>
> Key: SPARK-11337
> URL: https://issues.apache.org/jira/browse/SPARK-11337
> Project: Spark
> Issue Type: Umbrella
> Components: Documentation
> Reporter: Xiangrui Meng
> Assignee: Xusen Yin
> Priority: Critical
>
> The example code in the user guide is embedded in the markdown and hence it
> is not easy to test. It would be nice to automatically test them. This JIRA
> is to discuss options to automate example code testing and see what we can do
> in Spark 1.6.
> One option I propose is to move actual example code to spark/examples and
> test compilation in Jenkins builds. Then in the markdown, we can reference
> part of the code to show in the user guide. This requires adding a Jekyll tag
> that is similar to
> https://github.com/jekyll/jekyll/blob/master/lib/jekyll/tags/include.rb,
> e.g., called include_example.
> {code}
> {% include_example scala ml.KMeansExample guide %}
> {code}
> Jekyll will find
> `examples/src/main/scala/org/apache/spark/examples/ml/KMeansExample.scala`
> and pick code blocks marked "example" and put them under `{% highlight %}` in
> the markdown. We can discuss the syntax for marker comments.
> Sub-tasks are created to move example code from user guide to `examples/`.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
