You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lucene.apache.org by Mihály Tóth <mi...@gmail.com> on 2018/02/27 06:57:34 UTC
Re: Help needed in R documentation generation
Hi,
Actually, when I open the link you provided and click on - for example -
'sin' the page does not seem to describe that function at all. Actually I
get same effect that I get locally. I have attached a screenshot about that:
[image: Szövegközi kép 1]
I tried with Chrome and then with Safari too and got the same result.
When I go to https://spark.apache.org/docs/latest/api/R/index.html (Spark
2.2.1) and select 'sin' I get a proper Description, Usage, Arguments, etc.
sections.
This sounds like a bug in the documentation of Spark R, does'nt it? Shall I
file a Jira about it?
Best Regards,
Misi
> --------------------
> From: Felix Cheung <fe...@hotmail.com>
> Date: 2018-02-26 20:42 GMT+00:00
> Subject: Re: Help needed in R documentation generation
> To: Mihály Tóth <mi...@gmail.com>
> Cc: "dev@spark.apache.org" <de...@spark.apache.org>
>
>
> Could you tell me more about the steps you are taking? Which page you are
> clicking on?
>
> Could you try https://dist.apache.org/repos/dist/dev/spark/v2.3.0-rc5-docs
> /_site/api/R/index.html
>
> ------------------------------
> *From:* Mihály Tóth <mi...@gmail.com>
> *Sent:* Monday, February 26, 2018 8:06:59 AM
> *To:* Felix Cheung
> *Cc:* dev@spark.apache.org
> *Subject:* Re: Help needed in R documentation generation
>
> I see.
>
> When I click on such a selected function, like 'sin' the page falls apart
> and does not tell anything about sin function. How is it supposed to work
> when all functions link to the same column_math_functions.html ?
>
> Thanks,
>
> Misi
>
>
> On Sun, Feb 25, 2018, 22:53 Felix Cheung <fe...@hotmail.com>
> wrote:
>
>> This is recent change. The html file column_math_functions.html should
>> have the right help content.
>>
>> What is the problem you are experiencing?
>>
>> ------------------------------
>> *From:* Mihály Tóth <mi...@gmail.com>
>> *Sent:* Sunday, February 25, 2018 10:42:50 PM
>> *To:* dev@spark.apache.org
>> *Subject:* Help needed in R documentation generation
>>
>> Hi,
>>
>> I am having difficulties generating R documentation.
>>
>> In R/pkg/html/index.html file at the individual function entries it
>> reference
>> column_math_functions.html instead of the function page itself. Like
>>
>> <a href="column_math_functions.html">asin</a>
>>
>> Have you met with such a problem?
>>
>> Thanks,
>>
>> Misi
>>
>>
>>
>
Re: Help needed in R documentation generation
Posted by Mihály Tóth <mi...@gmail.com>.
Hmmm, definitely not. Sorry and thanks for replying.
Misi
2018-02-27 15:38 GMT+00:00 Erick Erickson <er...@gmail.com>:
> Hmmm, do you mean this to be coming to the Lucene dev mailing list? It
> doesn't look related....
>
> On Mon, Feb 26, 2018 at 11:11 PM, Mihály Tóth <mi...@gmail.com> wrote:
>
>> Locally I ran SPARK_HOME/R/create-docs.sh and it returned successfully.
>> Unfortunately with the result mentioned above.
>>
>> Best Regards,
>>
>> Misi
>>
>> 2018-02-27 6:57 GMT+00:00 Mihály Tóth <mi...@gmail.com>:
>>
>>> Hi,
>>>
>>> Actually, when I open the link you provided and click on - for example -
>>> 'sin' the page does not seem to describe that function at all. Actually I
>>> get same effect that I get locally. I have attached a screenshot about that:
>>>
>>>
>>> [image: Szövegközi kép 1]
>>>
>>>
>>> I tried with Chrome and then with Safari too and got the same result.
>>>
>>> When I go to https://spark.apache.org/docs/latest/api/R/index.html (Spark
>>> 2.2.1) and select 'sin' I get a proper Description, Usage, Arguments, etc.
>>> sections.
>>>
>>> This sounds like a bug in the documentation of Spark R, does'nt it?
>>> Shall I file a Jira about it?
>>>
>>> Best Regards,
>>>
>>> Misi
>>>
>>>
>>>
>>>> --------------------
>>>>
>>>> From: Felix Cheung <fe...@hotmail.com>
>>>> Date: 2018-02-26 20:42 GMT+00:00
>>>> Subject: Re: Help needed in R documentation generation
>>>> To: Mihály Tóth <mi...@gmail.com>
>>>> Cc: "dev@spark.apache.org" <de...@spark.apache.org>
>>>>
>>>>
>>>> Could you tell me more about the steps you are taking? Which page you
>>>> are clicking on?
>>>>
>>>> Could you try https://dist.apache.org/repos/
>>>> dist/dev/spark/v2.3.0-rc5-docs/_site/api/R/index.html
>>>>
>>>> ------------------------------
>>>> *From:* Mihály Tóth <mi...@gmail.com>
>>>> *Sent:* Monday, February 26, 2018 8:06:59 AM
>>>> *To:* Felix Cheung
>>>> *Cc:* dev@spark.apache.org
>>>> *Subject:* Re: Help needed in R documentation generation
>>>>
>>>> I see.
>>>>
>>>> When I click on such a selected function, like 'sin' the page falls
>>>> apart and does not tell anything about sin function. How is it supposed to
>>>> work when all functions link to the same column_math_functions.html ?
>>>>
>>>> Thanks,
>>>>
>>>> Misi
>>>>
>>>>
>>>> On Sun, Feb 25, 2018, 22:53 Felix Cheung <fe...@hotmail.com>
>>>> wrote:
>>>>
>>>>> This is recent change. The html file column_math_functions.html should
>>>>> have the right help content.
>>>>>
>>>>> What is the problem you are experiencing?
>>>>>
>>>>> ------------------------------
>>>>> *From:* Mihály Tóth <mi...@gmail.com>
>>>>> *Sent:* Sunday, February 25, 2018 10:42:50 PM
>>>>> *To:* dev@spark.apache.org
>>>>> *Subject:* Help needed in R documentation generation
>>>>>
>>>>> Hi,
>>>>>
>>>>> I am having difficulties generating R documentation.
>>>>>
>>>>> In R/pkg/html/index.html file at the individual function entries it
>>>>> reference
>>>>> column_math_functions.html instead of the function page itself. Like
>>>>>
>>>>> <a href="column_math_functions.html">asin</a>
>>>>>
>>>>> Have you met with such a problem?
>>>>>
>>>>> Thanks,
>>>>>
>>>>> Misi
>>>>>
>>>>>
>>>>>
>>>>
>>>
>>
>
Re: Help needed in R documentation generation
Posted by Erick Erickson <er...@gmail.com>.
Hmmm, do you mean this to be coming to the Lucene dev mailing list? It
doesn't look related....
On Mon, Feb 26, 2018 at 11:11 PM, Mihály Tóth <mi...@gmail.com> wrote:
> Locally I ran SPARK_HOME/R/create-docs.sh and it returned successfully.
> Unfortunately with the result mentioned above.
>
> Best Regards,
>
> Misi
>
> 2018-02-27 6:57 GMT+00:00 Mihály Tóth <mi...@gmail.com>:
>
>> Hi,
>>
>> Actually, when I open the link you provided and click on - for example -
>> 'sin' the page does not seem to describe that function at all. Actually I
>> get same effect that I get locally. I have attached a screenshot about that:
>>
>>
>> [image: Szövegközi kép 1]
>>
>>
>> I tried with Chrome and then with Safari too and got the same result.
>>
>> When I go to https://spark.apache.org/docs/latest/api/R/index.html (Spark
>> 2.2.1) and select 'sin' I get a proper Description, Usage, Arguments, etc.
>> sections.
>>
>> This sounds like a bug in the documentation of Spark R, does'nt it? Shall
>> I file a Jira about it?
>>
>> Best Regards,
>>
>> Misi
>>
>>
>>
>>> --------------------
>>>
>>> From: Felix Cheung <fe...@hotmail.com>
>>> Date: 2018-02-26 20:42 GMT+00:00
>>> Subject: Re: Help needed in R documentation generation
>>> To: Mihály Tóth <mi...@gmail.com>
>>> Cc: "dev@spark.apache.org" <de...@spark.apache.org>
>>>
>>>
>>> Could you tell me more about the steps you are taking? Which page you
>>> are clicking on?
>>>
>>> Could you try https://dist.apache.org/repos/
>>> dist/dev/spark/v2.3.0-rc5-docs/_site/api/R/index.html
>>>
>>> ------------------------------
>>> *From:* Mihály Tóth <mi...@gmail.com>
>>> *Sent:* Monday, February 26, 2018 8:06:59 AM
>>> *To:* Felix Cheung
>>> *Cc:* dev@spark.apache.org
>>> *Subject:* Re: Help needed in R documentation generation
>>>
>>> I see.
>>>
>>> When I click on such a selected function, like 'sin' the page falls
>>> apart and does not tell anything about sin function. How is it supposed to
>>> work when all functions link to the same column_math_functions.html ?
>>>
>>> Thanks,
>>>
>>> Misi
>>>
>>>
>>> On Sun, Feb 25, 2018, 22:53 Felix Cheung <fe...@hotmail.com>
>>> wrote:
>>>
>>>> This is recent change. The html file column_math_functions.html should
>>>> have the right help content.
>>>>
>>>> What is the problem you are experiencing?
>>>>
>>>> ------------------------------
>>>> *From:* Mihály Tóth <mi...@gmail.com>
>>>> *Sent:* Sunday, February 25, 2018 10:42:50 PM
>>>> *To:* dev@spark.apache.org
>>>> *Subject:* Help needed in R documentation generation
>>>>
>>>> Hi,
>>>>
>>>> I am having difficulties generating R documentation.
>>>>
>>>> In R/pkg/html/index.html file at the individual function entries it
>>>> reference
>>>> column_math_functions.html instead of the function page itself. Like
>>>>
>>>> <a href="column_math_functions.html">asin</a>
>>>>
>>>> Have you met with such a problem?
>>>>
>>>> Thanks,
>>>>
>>>> Misi
>>>>
>>>>
>>>>
>>>
>>
>
Re: Help needed in R documentation generation
Posted by Mihály Tóth <mi...@gmail.com>.
Locally I ran SPARK_HOME/R/create-docs.sh and it returned successfully.
Unfortunately with the result mentioned above.
Best Regards,
Misi
2018-02-27 6:57 GMT+00:00 Mihály Tóth <mi...@gmail.com>:
> Hi,
>
> Actually, when I open the link you provided and click on - for example -
> 'sin' the page does not seem to describe that function at all. Actually I
> get same effect that I get locally. I have attached a screenshot about that:
>
>
> [image: Szövegközi kép 1]
>
>
> I tried with Chrome and then with Safari too and got the same result.
>
> When I go to https://spark.apache.org/docs/latest/api/R/index.html (Spark
> 2.2.1) and select 'sin' I get a proper Description, Usage, Arguments, etc.
> sections.
>
> This sounds like a bug in the documentation of Spark R, does'nt it? Shall
> I file a Jira about it?
>
> Best Regards,
>
> Misi
>
>
>
>> --------------------
>>
>> From: Felix Cheung <fe...@hotmail.com>
>> Date: 2018-02-26 20:42 GMT+00:00
>> Subject: Re: Help needed in R documentation generation
>> To: Mihály Tóth <mi...@gmail.com>
>> Cc: "dev@spark.apache.org" <de...@spark.apache.org>
>>
>>
>> Could you tell me more about the steps you are taking? Which page you are
>> clicking on?
>>
>> Could you try https://dist.apache.org/repos/
>> dist/dev/spark/v2.3.0-rc5-docs/_site/api/R/index.html
>>
>> ------------------------------
>> *From:* Mihály Tóth <mi...@gmail.com>
>> *Sent:* Monday, February 26, 2018 8:06:59 AM
>> *To:* Felix Cheung
>> *Cc:* dev@spark.apache.org
>> *Subject:* Re: Help needed in R documentation generation
>>
>> I see.
>>
>> When I click on such a selected function, like 'sin' the page falls apart
>> and does not tell anything about sin function. How is it supposed to work
>> when all functions link to the same column_math_functions.html ?
>>
>> Thanks,
>>
>> Misi
>>
>>
>> On Sun, Feb 25, 2018, 22:53 Felix Cheung <fe...@hotmail.com>
>> wrote:
>>
>>> This is recent change. The html file column_math_functions.html should
>>> have the right help content.
>>>
>>> What is the problem you are experiencing?
>>>
>>> ------------------------------
>>> *From:* Mihály Tóth <mi...@gmail.com>
>>> *Sent:* Sunday, February 25, 2018 10:42:50 PM
>>> *To:* dev@spark.apache.org
>>> *Subject:* Help needed in R documentation generation
>>>
>>> Hi,
>>>
>>> I am having difficulties generating R documentation.
>>>
>>> In R/pkg/html/index.html file at the individual function entries it
>>> reference
>>> column_math_functions.html instead of the function page itself. Like
>>>
>>> <a href="column_math_functions.html">asin</a>
>>>
>>> Have you met with such a problem?
>>>
>>> Thanks,
>>>
>>> Misi
>>>
>>>
>>>
>>
>
Re: Help needed in R documentation generation
Posted by Marcelo Vanzin <va...@cloudera.com>.
Ok, it sounds like this was the intended behavior of the doc
changes... I'm not an R developer, so maybe the new docs make enough
sense, but the previous ones did look nicer.
On Tue, Feb 27, 2018 at 11:09 AM, Felix Cheung
<fe...@hotmail.com> wrote:
> I had agreed it was a compromise when it was proposed back in May 2017.
>
> I don’t think I can capture the long reviews and many discussed that went
> in, for further discussion please start from JIRA SPARK-20889.
>
>
>
> ________________________________
> From: Marcelo Vanzin <va...@cloudera.com>
> Sent: Tuesday, February 27, 2018 10:26:23 AM
> To: Felix Cheung
> Cc: Mihály Tóth; Mihály Tóth; dev@spark.apache.org
>
> Subject: Re: Help needed in R documentation generation
>
> I followed Misi's instructions:
> - click on
> https://dist.apache.org/repos/dist/dev/spark/v2.3.0-rc5-docs/_site/api/R/index.html
> - click on "s" at the top
> - find "sin" and click on it
>
> And that does not give me the documentation for the "sin" function.
> That leads to you to a really ugly list of functions that's basically
> unreadable. There's lots of things like this:
>
> ## S4 method for signature 'Column'
> abs(x)
>
> Which look to me like the docs weren't properly generated. So it
> doesn't look like it's a discoverability problem, it seems there's
> something odd going on with the new docs.
>
> On the previous version those same steps take me to a nicely formatted
> doc for the "sin" function.
>
>
>
> On Tue, Feb 27, 2018 at 10:14 AM, Felix Cheung
> <fe...@hotmail.com> wrote:
>> I think what you are calling out is discoverability of names from index -
>> I
>> agree this should be improved.
>>
>> There are several reasons for this change, if I recall, some are:
>>
>> - we have too many doc pages and a very long index page because of the
>> atypical large number of functions - many R packages only have dozens (or
>> a
>> dozen) and we have hundreds; this also affects discoverability
>>
>> - a side effect of high number of functions is that we have hundreds of
>> pages of cross links between functions in the same and different
>> categories
>> that are very hard to read or find
>>
>> - many function examples are too simple or incomplete - it would be good
>> to
>> make them runnable, for instance
>>
>> There was a proposal for a search feature on the doc index at one point,
>> IMO
>> that would be very useful and would address the discoverability issue.
>>
>>
>> ________________________________
>> From: Mihály Tóth <mi...@gmail.com>
>> Sent: Tuesday, February 27, 2018 9:13:18 AM
>> To: Felix Cheung
>> Cc: Mihály Tóth; dev@spark.apache.org
>>
>> Subject: Re: Help needed in R documentation generation
>>
>> Hi,
>>
>> Earlier, at https://spark.apache.org/docs/latest/api/R/index.html I see
>>
>> sin as a title
>> description describes what sin does
>> usage, arguments, note, see also are specific to sin function
>>
>> When opening sin from
>>
>> https://dist.apache.org/repos/dist/dev/spark/v2.3.0-rc5-docs/_site/api/R/index.html:
>>
>> Title is 'Math functions for Column operations', not very specific to sin
>> Description is 'Math functions defined for Column.'
>> Usage contains a list of functions, scrolling down you can see sin as well
>> though ...
>>
>> To me that sounds like a problem. Do I overlook something here?
>>
>> Best Regards,
>> Misi
>>
>>
>> 2018-02-27 16:15 GMT+00:00 Felix Cheung <fe...@hotmail.com>:
>>>
>>> The help content on sin is in
>>>
>>>
>>> https://dist.apache.org/repos/dist/dev/spark/v2.3.0-rc5-docs/_site/api/R/column_math_functions.html
>>>
>>> It’s a fairly long list but sin is in there. Is that not what you are
>>> seeing?
>>>
>>>
>>> ________________________________
>>> From: Mihály Tóth <mt...@cloudera.com>
>>> Sent: Tuesday, February 27, 2018 8:03:34 AM
>>> To: dev@spark.apache.org
>>> Subject: Fwd: Help needed in R documentation generation
>>>
>>> Hi,
>>>
>>> Actually, when I open the link you provided and click on - for example -
>>> 'sin' the page does not seem to describe that function at all. Actually I
>>> get same effect that I get locally. I have attached a screenshot about
>>> that:
>>>
>>>
>>>
>>>
>>>
>>> I tried with Chrome and then with Safari too and got the same result.
>>>
>>> When I go to https://spark.apache.org/docs/latest/api/R/index.html (Spark
>>> 2.2.1) and select 'sin' I get a proper Description, Usage, Arguments,
>>> etc.
>>> sections.
>>>
>>> This sounds like a bug in the documentation of Spark R, does'nt it? Shall
>>> I file a Jira about it?
>>>
>>> Locally I ran SPARK_HOME/R/create-docs.sh and it returned successfully.
>>> Unfortunately with the result mentioned above.
>>>
>>> Best Regards,
>>>
>>> Misi
>>>
>>>
>>>>
>>>> --------------------
>>>>
>>>> From: Felix Cheung <fe...@hotmail.com>
>>>> Date: 2018-02-26 20:42 GMT+00:00
>>>> Subject: Re: Help needed in R documentation generation
>>>> To: Mihály Tóth <mi...@gmail.com>
>>>> Cc: "dev@spark.apache.org" <de...@spark.apache.org>
>>>>
>>>>
>>>> Could you tell me more about the steps you are taking? Which page you
>>>> are
>>>> clicking on?
>>>>
>>>> Could you try
>>>>
>>>> https://dist.apache.org/repos/dist/dev/spark/v2.3.0-rc5-docs/_site/api/R/index.html
>>>>
>>>> ________________________________
>>>> From: Mihály Tóth <mi...@gmail.com>
>>>> Sent: Monday, February 26, 2018 8:06:59 AM
>>>> To: Felix Cheung
>>>> Cc: dev@spark.apache.org
>>>> Subject: Re: Help needed in R documentation generation
>>>>
>>>> I see.
>>>>
>>>> When I click on such a selected function, like 'sin' the page falls
>>>> apart
>>>> and does not tell anything about sin function. How is it supposed to
>>>> work
>>>> when all functions link to the same column_math_functions.html ?
>>>>
>>>> Thanks,
>>>>
>>>> Misi
>>>>
>>>>
>>>> On Sun, Feb 25, 2018, 22:53 Felix Cheung <fe...@hotmail.com>
>>>> wrote:
>>>>>
>>>>> This is recent change. The html file column_math_functions.html should
>>>>> have the right help content.
>>>>>
>>>>> What is the problem you are experiencing?
>>>>>
>>>>> ________________________________
>>>>> From: Mihály Tóth <mi...@gmail.com>
>>>>> Sent: Sunday, February 25, 2018 10:42:50 PM
>>>>> To: dev@spark.apache.org
>>>>> Subject: Help needed in R documentation generation
>>>>>
>>>>> Hi,
>>>>>
>>>>> I am having difficulties generating R documentation.
>>>>>
>>>>> In R/pkg/html/index.html file at the individual function entries it
>>>>> reference
>>>>> column_math_functions.html instead of the function page itself. Like
>>>>>
>>>>> <a href="column_math_functions.html">asin</a>
>>>>>
>>>>> Have you met with such a problem?
>>>>>
>>>>> Thanks,
>>>>>
>>>>> Misi
>>>>>
>>>>>
>>>>
>>>
>>>
>>
>
>
>
> --
> Marcelo
--
Marcelo
---------------------------------------------------------------------
To unsubscribe e-mail: dev-unsubscribe@spark.apache.org
Re: Help needed in R documentation generation
Posted by Felix Cheung <fe...@hotmail.com>.
I had agreed it was a compromise when it was proposed back in May 2017.
I don’t think I can capture the long reviews and many discussed that went in, for further discussion please start from JIRA SPARK-20889.
________________________________
From: Marcelo Vanzin <va...@cloudera.com>
Sent: Tuesday, February 27, 2018 10:26:23 AM
To: Felix Cheung
Cc: Mihály Tóth; Mihály Tóth; dev@spark.apache.org
Subject: Re: Help needed in R documentation generation
I followed Misi's instructions:
- click on https://dist.apache.org/repos/dist/dev/spark/v2.3.0-rc5-docs/_site/api/R/index.html
- click on "s" at the top
- find "sin" and click on it
And that does not give me the documentation for the "sin" function.
That leads to you to a really ugly list of functions that's basically
unreadable. There's lots of things like this:
## S4 method for signature 'Column'
abs(x)
Which look to me like the docs weren't properly generated. So it
doesn't look like it's a discoverability problem, it seems there's
something odd going on with the new docs.
On the previous version those same steps take me to a nicely formatted
doc for the "sin" function.
On Tue, Feb 27, 2018 at 10:14 AM, Felix Cheung
<fe...@hotmail.com> wrote:
> I think what you are calling out is discoverability of names from index - I
> agree this should be improved.
>
> There are several reasons for this change, if I recall, some are:
>
> - we have too many doc pages and a very long index page because of the
> atypical large number of functions - many R packages only have dozens (or a
> dozen) and we have hundreds; this also affects discoverability
>
> - a side effect of high number of functions is that we have hundreds of
> pages of cross links between functions in the same and different categories
> that are very hard to read or find
>
> - many function examples are too simple or incomplete - it would be good to
> make them runnable, for instance
>
> There was a proposal for a search feature on the doc index at one point, IMO
> that would be very useful and would address the discoverability issue.
>
>
> ________________________________
> From: Mihály Tóth <mi...@gmail.com>
> Sent: Tuesday, February 27, 2018 9:13:18 AM
> To: Felix Cheung
> Cc: Mihály Tóth; dev@spark.apache.org
>
> Subject: Re: Help needed in R documentation generation
>
> Hi,
>
> Earlier, at https://spark.apache.org/docs/latest/api/R/index.html I see
>
> sin as a title
> description describes what sin does
> usage, arguments, note, see also are specific to sin function
>
> When opening sin from
> https://dist.apache.org/repos/dist/dev/spark/v2.3.0-rc5-docs/_site/api/R/index.html:
>
> Title is 'Math functions for Column operations', not very specific to sin
> Description is 'Math functions defined for Column.'
> Usage contains a list of functions, scrolling down you can see sin as well
> though ...
>
> To me that sounds like a problem. Do I overlook something here?
>
> Best Regards,
> Misi
>
>
> 2018-02-27 16:15 GMT+00:00 Felix Cheung <fe...@hotmail.com>:
>>
>> The help content on sin is in
>>
>> https://dist.apache.org/repos/dist/dev/spark/v2.3.0-rc5-docs/_site/api/R/column_math_functions.html
>>
>> It’s a fairly long list but sin is in there. Is that not what you are
>> seeing?
>>
>>
>> ________________________________
>> From: Mihály Tóth <mt...@cloudera.com>
>> Sent: Tuesday, February 27, 2018 8:03:34 AM
>> To: dev@spark.apache.org
>> Subject: Fwd: Help needed in R documentation generation
>>
>> Hi,
>>
>> Actually, when I open the link you provided and click on - for example -
>> 'sin' the page does not seem to describe that function at all. Actually I
>> get same effect that I get locally. I have attached a screenshot about that:
>>
>>
>>
>>
>>
>> I tried with Chrome and then with Safari too and got the same result.
>>
>> When I go to https://spark.apache.org/docs/latest/api/R/index.html (Spark
>> 2.2.1) and select 'sin' I get a proper Description, Usage, Arguments, etc.
>> sections.
>>
>> This sounds like a bug in the documentation of Spark R, does'nt it? Shall
>> I file a Jira about it?
>>
>> Locally I ran SPARK_HOME/R/create-docs.sh and it returned successfully.
>> Unfortunately with the result mentioned above.
>>
>> Best Regards,
>>
>> Misi
>>
>>
>>>
>>> --------------------
>>>
>>> From: Felix Cheung <fe...@hotmail.com>
>>> Date: 2018-02-26 20:42 GMT+00:00
>>> Subject: Re: Help needed in R documentation generation
>>> To: Mihály Tóth <mi...@gmail.com>
>>> Cc: "dev@spark.apache.org" <de...@spark.apache.org>
>>>
>>>
>>> Could you tell me more about the steps you are taking? Which page you are
>>> clicking on?
>>>
>>> Could you try
>>> https://dist.apache.org/repos/dist/dev/spark/v2.3.0-rc5-docs/_site/api/R/index.html
>>>
>>> ________________________________
>>> From: Mihály Tóth <mi...@gmail.com>
>>> Sent: Monday, February 26, 2018 8:06:59 AM
>>> To: Felix Cheung
>>> Cc: dev@spark.apache.org
>>> Subject: Re: Help needed in R documentation generation
>>>
>>> I see.
>>>
>>> When I click on such a selected function, like 'sin' the page falls apart
>>> and does not tell anything about sin function. How is it supposed to work
>>> when all functions link to the same column_math_functions.html ?
>>>
>>> Thanks,
>>>
>>> Misi
>>>
>>>
>>> On Sun, Feb 25, 2018, 22:53 Felix Cheung <fe...@hotmail.com>
>>> wrote:
>>>>
>>>> This is recent change. The html file column_math_functions.html should
>>>> have the right help content.
>>>>
>>>> What is the problem you are experiencing?
>>>>
>>>> ________________________________
>>>> From: Mihály Tóth <mi...@gmail.com>
>>>> Sent: Sunday, February 25, 2018 10:42:50 PM
>>>> To: dev@spark.apache.org
>>>> Subject: Help needed in R documentation generation
>>>>
>>>> Hi,
>>>>
>>>> I am having difficulties generating R documentation.
>>>>
>>>> In R/pkg/html/index.html file at the individual function entries it
>>>> reference
>>>> column_math_functions.html instead of the function page itself. Like
>>>>
>>>> <a href="column_math_functions.html">asin</a>
>>>>
>>>> Have you met with such a problem?
>>>>
>>>> Thanks,
>>>>
>>>> Misi
>>>>
>>>>
>>>
>>
>>
>
--
Marcelo
Re: Help needed in R documentation generation
Posted by Marcelo Vanzin <va...@cloudera.com>.
I followed Misi's instructions:
- click on https://dist.apache.org/repos/dist/dev/spark/v2.3.0-rc5-docs/_site/api/R/index.html
- click on "s" at the top
- find "sin" and click on it
And that does not give me the documentation for the "sin" function.
That leads to you to a really ugly list of functions that's basically
unreadable. There's lots of things like this:
## S4 method for signature 'Column'
abs(x)
Which look to me like the docs weren't properly generated. So it
doesn't look like it's a discoverability problem, it seems there's
something odd going on with the new docs.
On the previous version those same steps take me to a nicely formatted
doc for the "sin" function.
On Tue, Feb 27, 2018 at 10:14 AM, Felix Cheung
<fe...@hotmail.com> wrote:
> I think what you are calling out is discoverability of names from index - I
> agree this should be improved.
>
> There are several reasons for this change, if I recall, some are:
>
> - we have too many doc pages and a very long index page because of the
> atypical large number of functions - many R packages only have dozens (or a
> dozen) and we have hundreds; this also affects discoverability
>
> - a side effect of high number of functions is that we have hundreds of
> pages of cross links between functions in the same and different categories
> that are very hard to read or find
>
> - many function examples are too simple or incomplete - it would be good to
> make them runnable, for instance
>
> There was a proposal for a search feature on the doc index at one point, IMO
> that would be very useful and would address the discoverability issue.
>
>
> ________________________________
> From: Mihály Tóth <mi...@gmail.com>
> Sent: Tuesday, February 27, 2018 9:13:18 AM
> To: Felix Cheung
> Cc: Mihály Tóth; dev@spark.apache.org
>
> Subject: Re: Help needed in R documentation generation
>
> Hi,
>
> Earlier, at https://spark.apache.org/docs/latest/api/R/index.html I see
>
> sin as a title
> description describes what sin does
> usage, arguments, note, see also are specific to sin function
>
> When opening sin from
> https://dist.apache.org/repos/dist/dev/spark/v2.3.0-rc5-docs/_site/api/R/index.html:
>
> Title is 'Math functions for Column operations', not very specific to sin
> Description is 'Math functions defined for Column.'
> Usage contains a list of functions, scrolling down you can see sin as well
> though ...
>
> To me that sounds like a problem. Do I overlook something here?
>
> Best Regards,
> Misi
>
>
> 2018-02-27 16:15 GMT+00:00 Felix Cheung <fe...@hotmail.com>:
>>
>> The help content on sin is in
>>
>> https://dist.apache.org/repos/dist/dev/spark/v2.3.0-rc5-docs/_site/api/R/column_math_functions.html
>>
>> It’s a fairly long list but sin is in there. Is that not what you are
>> seeing?
>>
>>
>> ________________________________
>> From: Mihály Tóth <mt...@cloudera.com>
>> Sent: Tuesday, February 27, 2018 8:03:34 AM
>> To: dev@spark.apache.org
>> Subject: Fwd: Help needed in R documentation generation
>>
>> Hi,
>>
>> Actually, when I open the link you provided and click on - for example -
>> 'sin' the page does not seem to describe that function at all. Actually I
>> get same effect that I get locally. I have attached a screenshot about that:
>>
>>
>>
>>
>>
>> I tried with Chrome and then with Safari too and got the same result.
>>
>> When I go to https://spark.apache.org/docs/latest/api/R/index.html (Spark
>> 2.2.1) and select 'sin' I get a proper Description, Usage, Arguments, etc.
>> sections.
>>
>> This sounds like a bug in the documentation of Spark R, does'nt it? Shall
>> I file a Jira about it?
>>
>> Locally I ran SPARK_HOME/R/create-docs.sh and it returned successfully.
>> Unfortunately with the result mentioned above.
>>
>> Best Regards,
>>
>> Misi
>>
>>
>>>
>>> --------------------
>>>
>>> From: Felix Cheung <fe...@hotmail.com>
>>> Date: 2018-02-26 20:42 GMT+00:00
>>> Subject: Re: Help needed in R documentation generation
>>> To: Mihály Tóth <mi...@gmail.com>
>>> Cc: "dev@spark.apache.org" <de...@spark.apache.org>
>>>
>>>
>>> Could you tell me more about the steps you are taking? Which page you are
>>> clicking on?
>>>
>>> Could you try
>>> https://dist.apache.org/repos/dist/dev/spark/v2.3.0-rc5-docs/_site/api/R/index.html
>>>
>>> ________________________________
>>> From: Mihály Tóth <mi...@gmail.com>
>>> Sent: Monday, February 26, 2018 8:06:59 AM
>>> To: Felix Cheung
>>> Cc: dev@spark.apache.org
>>> Subject: Re: Help needed in R documentation generation
>>>
>>> I see.
>>>
>>> When I click on such a selected function, like 'sin' the page falls apart
>>> and does not tell anything about sin function. How is it supposed to work
>>> when all functions link to the same column_math_functions.html ?
>>>
>>> Thanks,
>>>
>>> Misi
>>>
>>>
>>> On Sun, Feb 25, 2018, 22:53 Felix Cheung <fe...@hotmail.com>
>>> wrote:
>>>>
>>>> This is recent change. The html file column_math_functions.html should
>>>> have the right help content.
>>>>
>>>> What is the problem you are experiencing?
>>>>
>>>> ________________________________
>>>> From: Mihály Tóth <mi...@gmail.com>
>>>> Sent: Sunday, February 25, 2018 10:42:50 PM
>>>> To: dev@spark.apache.org
>>>> Subject: Help needed in R documentation generation
>>>>
>>>> Hi,
>>>>
>>>> I am having difficulties generating R documentation.
>>>>
>>>> In R/pkg/html/index.html file at the individual function entries it
>>>> reference
>>>> column_math_functions.html instead of the function page itself. Like
>>>>
>>>> <a href="column_math_functions.html">asin</a>
>>>>
>>>> Have you met with such a problem?
>>>>
>>>> Thanks,
>>>>
>>>> Misi
>>>>
>>>>
>>>
>>
>>
>
--
Marcelo
---------------------------------------------------------------------
To unsubscribe e-mail: dev-unsubscribe@spark.apache.org
Re: Help needed in R documentation generation
Posted by Felix Cheung <fe...@hotmail.com>.
I think what you are calling out is discoverability of names from index - I agree this should be improved.
There are several reasons for this change, if I recall, some are:
- we have too many doc pages and a very long index page because of the atypical large number of functions - many R packages only have dozens (or a dozen) and we have hundreds; this also affects discoverability
- a side effect of high number of functions is that we have hundreds of pages of cross links between functions in the same and different categories that are very hard to read or find
- many function examples are too simple or incomplete - it would be good to make them runnable, for instance
There was a proposal for a search feature on the doc index at one point, IMO that would be very useful and would address the discoverability issue.
________________________________
From: Mihály Tóth <mi...@gmail.com>
Sent: Tuesday, February 27, 2018 9:13:18 AM
To: Felix Cheung
Cc: Mihály Tóth; dev@spark.apache.org
Subject: Re: Help needed in R documentation generation
Hi,
Earlier, at https://spark.apache.org/docs/latest/api/R/index.html I see
1. sin as a title
2. description describes what sin does
3. usage, arguments, note, see also are specific to sin function
When opening sin from https://dist.apache.org/repos/dist/dev/spark/v2.3.0-rc5-docs/_site/api/R/index.html:
1. Title is 'Math functions for Column operations', not very specific to sin
2. Description is 'Math functions defined for Column.'
3. Usage contains a list of functions, scrolling down you can see sin as well though ...
To me that sounds like a problem. Do I overlook something here?
Best Regards,
Misi
2018-02-27 16:15 GMT+00:00 Felix Cheung <fe...@hotmail.com>>:
The help content on sin is in
https://dist.apache.org/repos/dist/dev/spark/v2.3.0-rc5-docs/_site/api/R/column_math_functions.html
It’s a fairly long list but sin is in there. Is that not what you are seeing?
________________________________
From: Mihály Tóth <mt...@cloudera.com>>
Sent: Tuesday, February 27, 2018 8:03:34 AM
To: dev@spark.apache.org<ma...@spark.apache.org>
Subject: Fwd: Help needed in R documentation generation
Hi,
Actually, when I open the link you provided and click on - for example - 'sin' the page does not seem to describe that function at all. Actually I get same effect that I get locally. I have attached a screenshot about that:
[Szövegközi kép 1]
I tried with Chrome and then with Safari too and got the same result.
When I go to https://spark.apache.org/docs/latest/api/R/index.html (Spark 2.2.1) and select 'sin' I get a proper Description, Usage, Arguments, etc. sections.
This sounds like a bug in the documentation of Spark R, does'nt it? Shall I file a Jira about it?
Locally I ran SPARK_HOME/R/create-docs.sh and it returned successfully. Unfortunately with the result mentioned above.
Best Regards,
Misi
--------------------
From: Felix Cheung <fe...@hotmail.com>>
Date: 2018-02-26 20:42 GMT+00:00
Subject: Re: Help needed in R documentation generation
To: Mihály Tóth <mi...@gmail.com>>
Cc: "dev@spark.apache.org<ma...@spark.apache.org>" <de...@spark.apache.org>>
Could you tell me more about the steps you are taking? Which page you are clicking on?
Could you try https://dist.apache.org/repos/dist/dev/spark/v2.3.0-rc5-docs/_site/api/R/index.html
________________________________
From: Mihály Tóth <mi...@gmail.com>>
Sent: Monday, February 26, 2018 8:06:59 AM
To: Felix Cheung
Cc: dev@spark.apache.org<ma...@spark.apache.org>
Subject: Re: Help needed in R documentation generation
I see.
When I click on such a selected function, like 'sin' the page falls apart and does not tell anything about sin function. How is it supposed to work when all functions link to the same column_math_functions.html ?
Thanks,
Misi
On Sun, Feb 25, 2018, 22:53 Felix Cheung <fe...@hotmail.com>> wrote:
This is recent change. The html file column_math_functions.html should have the right help content.
What is the problem you are experiencing?
________________________________
From: Mihály Tóth <mi...@gmail.com>>
Sent: Sunday, February 25, 2018 10:42:50 PM
To: dev@spark.apache.org<ma...@spark.apache.org>
Subject: Help needed in R documentation generation
Hi,
I am having difficulties generating R documentation.
In R/pkg/html/index.html file at the individual function entries it reference
column_math_functions.html instead of the function page itself. Like
<a href="column_math_functions.ht<http://column_math_functions.ht>ml">asin</a>
Have you met with such a problem?
Thanks,
Misi
Re: Help needed in R documentation generation
Posted by Mihály Tóth <mi...@gmail.com>.
Hi,
Earlier, at https://spark.apache.org/docs/latest/api/R/index.html I see
1. sin as a title
2. description describes what sin does
3. usage, arguments, note, see also are specific to sin function
When opening sin from
https://dist.apache.org/repos/dist/dev/spark/v2.3.0-rc5-docs/_site/api/R/index.html
:
1. Title is 'Math functions for Column operations', not very specific to
sin
2. Description is 'Math functions defined for Column.'
3. Usage contains a list of functions, scrolling down you can see sin as
well though ...
To me that sounds like a problem. Do I overlook something here?
Best Regards,
Misi
2018-02-27 16:15 GMT+00:00 Felix Cheung <fe...@hotmail.com>:
> The help content on sin is in
> https://dist.apache.org/repos/dist/dev/spark/v2.3.0-rc5-
> docs/_site/api/R/column_math_functions.html
>
> It’s a fairly long list but sin is in there. Is that not what you are
> seeing?
>
>
> ------------------------------
> *From:* Mihály Tóth <mt...@cloudera.com>
> *Sent:* Tuesday, February 27, 2018 8:03:34 AM
> *To:* dev@spark.apache.org
> *Subject:* Fwd: Help needed in R documentation generation
>
> Hi,
>
> Actually, when I open the link you provided and click on - for example -
> 'sin' the page does not seem to describe that function at all. Actually I
> get same effect that I get locally. I have attached a screenshot about that:
>
>
> [image: Szövegközi kép 1]
>
>
> I tried with Chrome and then with Safari too and got the same result.
>
> When I go to https://spark.apache.org/docs/latest/api/R/index.html (Spark
> 2.2.1) and select 'sin' I get a proper Description, Usage, Arguments, etc.
> sections.
>
> This sounds like a bug in the documentation of Spark R, does'nt it? Shall
> I file a Jira about it?
>
> Locally I ran SPARK_HOME/R/create-docs.sh and it returned successfully.
> Unfortunately with the result mentioned above.
>
> Best Regards,
>
> Misi
>
>
>
>> --------------------
>>
>> From: Felix Cheung <fe...@hotmail.com>
>> Date: 2018-02-26 20:42 GMT+00:00
>> Subject: Re: Help needed in R documentation generation
>> To: Mihály Tóth <mi...@gmail.com>
>> Cc: "dev@spark.apache.org" <de...@spark.apache.org>
>>
>>
>> Could you tell me more about the steps you are taking? Which page you are
>> clicking on?
>>
>> Could you try https://dist.apache.org/repos/
>> dist/dev/spark/v2.3.0-rc5-docs/_site/api/R/index.html
>>
>> ------------------------------
>> *From:* Mihály Tóth <mi...@gmail.com>
>> *Sent:* Monday, February 26, 2018 8:06:59 AM
>> *To:* Felix Cheung
>> *Cc:* dev@spark.apache.org
>> *Subject:* Re: Help needed in R documentation generation
>>
>> I see.
>>
>> When I click on such a selected function, like 'sin' the page falls apart
>> and does not tell anything about sin function. How is it supposed to work
>> when all functions link to the same column_math_functions.html ?
>>
>> Thanks,
>>
>> Misi
>>
>>
>> On Sun, Feb 25, 2018, 22:53 Felix Cheung <fe...@hotmail.com>
>> wrote:
>>
>>> This is recent change. The html file column_math_functions.html should
>>> have the right help content.
>>>
>>> What is the problem you are experiencing?
>>>
>>> ------------------------------
>>> *From:* Mihály Tóth <mi...@gmail.com>
>>> *Sent:* Sunday, February 25, 2018 10:42:50 PM
>>> *To:* dev@spark.apache.org
>>> *Subject:* Help needed in R documentation generation
>>>
>>> Hi,
>>>
>>> I am having difficulties generating R documentation.
>>>
>>> In R/pkg/html/index.html file at the individual function entries it
>>> reference
>>> column_math_functions.html instead of the function page itself. Like
>>>
>>> <a href="column_math_functions.html">asin</a>
>>>
>>> Have you met with such a problem?
>>>
>>> Thanks,
>>>
>>> Misi
>>>
>>>
>>>
>>
>
>
Re: Help needed in R documentation generation
Posted by Felix Cheung <fe...@hotmail.com>.
The help content on sin is in
https://dist.apache.org/repos/dist/dev/spark/v2.3.0-rc5-docs/_site/api/R/column_math_functions.html
It’s a fairly long list but sin is in there. Is that not what you are seeing?
________________________________
From: Mihály Tóth <mt...@cloudera.com>
Sent: Tuesday, February 27, 2018 8:03:34 AM
To: dev@spark.apache.org
Subject: Fwd: Help needed in R documentation generation
Hi,
Actually, when I open the link you provided and click on - for example - 'sin' the page does not seem to describe that function at all. Actually I get same effect that I get locally. I have attached a screenshot about that:
[Szövegközi kép 1]
I tried with Chrome and then with Safari too and got the same result.
When I go to https://spark.apache.org/docs/latest/api/R/index.html (Spark 2.2.1) and select 'sin' I get a proper Description, Usage, Arguments, etc. sections.
This sounds like a bug in the documentation of Spark R, does'nt it? Shall I file a Jira about it?
Locally I ran SPARK_HOME/R/create-docs.sh and it returned successfully. Unfortunately with the result mentioned above.
Best Regards,
Misi
--------------------
From: Felix Cheung <fe...@hotmail.com>>
Date: 2018-02-26 20:42 GMT+00:00
Subject: Re: Help needed in R documentation generation
To: Mihály Tóth <mi...@gmail.com>>
Cc: "dev@spark.apache.org<ma...@spark.apache.org>" <de...@spark.apache.org>>
Could you tell me more about the steps you are taking? Which page you are clicking on?
Could you try https://dist.apache.org/repos/dist/dev/spark/v2.3.0-rc5-docs/_site/api/R/index.html
________________________________
From: Mihály Tóth <mi...@gmail.com>>
Sent: Monday, February 26, 2018 8:06:59 AM
To: Felix Cheung
Cc: dev@spark.apache.org<ma...@spark.apache.org>
Subject: Re: Help needed in R documentation generation
I see.
When I click on such a selected function, like 'sin' the page falls apart and does not tell anything about sin function. How is it supposed to work when all functions link to the same column_math_functions.html ?
Thanks,
Misi
On Sun, Feb 25, 2018, 22:53 Felix Cheung <fe...@hotmail.com>> wrote:
This is recent change. The html file column_math_functions.html should have the right help content.
What is the problem you are experiencing?
________________________________
From: Mihály Tóth <mi...@gmail.com>>
Sent: Sunday, February 25, 2018 10:42:50 PM
To: dev@spark.apache.org<ma...@spark.apache.org>
Subject: Help needed in R documentation generation
Hi,
I am having difficulties generating R documentation.
In R/pkg/html/index.html file at the individual function entries it reference
column_math_functions.html instead of the function page itself. Like
<a href="column_math_functions.ht<http://column_math_functions.ht>ml">asin</a>
Have you met with such a problem?
Thanks,
Misi
Fwd: Help needed in R documentation generation
Posted by Mihály Tóth <mt...@cloudera.com>.
Hi,
Actually, when I open the link you provided and click on - for example -
'sin' the page does not seem to describe that function at all. Actually I
get same effect that I get locally. I have attached a screenshot about that:
[image: Szövegközi kép 1]
I tried with Chrome and then with Safari too and got the same result.
When I go to https://spark.apache.org/docs/latest/api/R/index.html (Spark
2.2.1) and select 'sin' I get a proper Description, Usage, Arguments, etc.
sections.
This sounds like a bug in the documentation of Spark R, does'nt it? Shall I
file a Jira about it?
Locally I ran SPARK_HOME/R/create-docs.sh and it returned successfully.
Unfortunately with the result mentioned above.
Best Regards,
Misi
> --------------------
>
> From: Felix Cheung <fe...@hotmail.com>
> Date: 2018-02-26 20:42 GMT+00:00
> Subject: Re: Help needed in R documentation generation
> To: Mihály Tóth <mi...@gmail.com>
> Cc: "dev@spark.apache.org" <de...@spark.apache.org>
>
>
> Could you tell me more about the steps you are taking? Which page you are
> clicking on?
>
> Could you try https://dist.apache.org/repos/dist/dev/spark/v2.3.0-rc5-docs
> /_site/api/R/index.html
>
> ------------------------------
> *From:* Mihály Tóth <mi...@gmail.com>
> *Sent:* Monday, February 26, 2018 8:06:59 AM
> *To:* Felix Cheung
> *Cc:* dev@spark.apache.org
> *Subject:* Re: Help needed in R documentation generation
>
> I see.
>
> When I click on such a selected function, like 'sin' the page falls apart
> and does not tell anything about sin function. How is it supposed to work
> when all functions link to the same column_math_functions.html ?
>
> Thanks,
>
> Misi
>
>
> On Sun, Feb 25, 2018, 22:53 Felix Cheung <fe...@hotmail.com>
> wrote:
>
>> This is recent change. The html file column_math_functions.html should
>> have the right help content.
>>
>> What is the problem you are experiencing?
>>
>> ------------------------------
>> *From:* Mihály Tóth <mi...@gmail.com>
>> *Sent:* Sunday, February 25, 2018 10:42:50 PM
>> *To:* dev@spark.apache.org
>> *Subject:* Help needed in R documentation generation
>>
>> Hi,
>>
>> I am having difficulties generating R documentation.
>>
>> In R/pkg/html/index.html file at the individual function entries it
>> reference
>> column_math_functions.html instead of the function page itself. Like
>>
>> <a href="column_math_functions.html">asin</a>
>>
>> Have you met with such a problem?
>>
>> Thanks,
>>
>> Misi
>>
>>
>>
>