Googling the functions I need in Julia is hard

[Po Choi]

One thing I hate Julia is that it is very hard to google for the functions I need. I feel like Julia has no documentation.

If I google "R standard deviation", the first link is

https://stat.ethz.ch/R-manual/R-devel/library/stats/html/sd.html

which tells all the things about the standard deviation function in R

If I google "Matlab standard deviation", the first link is

http://www.mathworks.com/help/matlab/ref/std.html

which tells all the things about the standard deviation function in Matlab.

If I google "julia standard deviation", there are just some random pages which are very confusing.

Any tips for how to google for the functions I need in Julia?

Could Julia have a nice user manual like R or Matlab?

[Lutfullah Tomak]

There is this one

http://docs.julialang.org/en/release-0.4/stdlib/math/#Base.std

Instead of google, I use this manual for search.

[NotSoRecentConvert]

You can even download the entire thing as a PDF, HTML, or EPUB if you want to highlight, annotate, or bookmark your most searched functions. Look in the lower right of the page for "v: latest" and click it for more options.

[Mauro]

Also at the Julia REPL:

julia> apropos("standard deviation")
randn!
stdm
std
randn

help?> std
search: std stdm STDIN STDOUT STDERR setdiff setdiff! hist2d hist2d! stride strides StridedArray StridedVector StridedMatrix StridedVecOrMat redirect_stdin

std(v[, region])

Compute the sample standard deviation of a vector or array v, optionally along dimensions in region. The algorithm returns an estimator of the generative
distribution's standard deviation under the assumption that each entry of v is an IID drawn from that generative distribution. This computation is equivalent to
calculating sqrt(sum((v - mean(v)).^2) / (length(v) - 1)). Note: Julia does not ignore NaN values in the computation. For applications requiring the handling of
missing data, the DataArray package is recommended.

Having said this, documentation always needs improvements and is
certainly not on Matlab's level of completeness. Please contribute
where you find it lacking. See
https://github.com/JuliaLang/julia/blob/master/CONTRIBUTING.md#improving-documentation

[Michele Zaffalon]

But the original point is still valid: using the search box in the official documentation page http://docs.julialang.org/en/release-0.4, searching for "standard deviation" does not bring up any useful hit, despite the fact that Base.std is fairly well documented and contains the words standard deviation.

Is there a reason why it should work at the REPL but not in the webpage?

[Lutfullah Tomak]

For reference, I had used just 'deviation'.

http://docs.julialang.org/en/release-0.4/search/?q=deviation&check_keywords=yes&area=default#

Another instance of 'standard deviation' shows up in the search but this one when 'standard deviation' is searched.

[Michele Zaffalon]

On mine, it points to the functions randn and randn!

On Fri, Feb 12, 2016 at 11:48 AM, Lutfullah Tomak <tomak...@gmail.com> wrote:

For reference, it shows up in my search.

http://docs.julialang.org/en/release-0.4/search/?q=standard+deviation&check_keywords=yes&area=default

About google side, I think that MATLAB and R are used for years and thus results are indexed better for them.

[Lutfullah Tomak]

Sorry deleted that post because that wasn't I used.

[Milan Bouchet-Valat]

Le vendredi 12 février 2016 à 09:51 +0100, Michele Zaffalon a écrit :
> But the original point is still valid: using the search box in the
> official documentation page http://docs.julialang.org/en/release-0.4,
> searching for "standard deviation" does not bring up any useful hit,
> despite the fact that Base.std is fairly well documented and contains
> the words standard deviation.
> Is there a reason why it should work at the REPL but not in the
> webpage?

Searching for "deviation" works, so it's quite mysterious that
"standard deviation" doesn't... Looks like a bug in the Sphinx search
engine.

Google's behavior is really weird too. Even a query like "standard
deviation julia site:docs.julialang.org" gives the manual page home for
the standard library first (even if it doesn't contain "deviation"), as
well as pages mentioning "standard error". Maybe some pages are not
indexed at all? Could something be tweaked in the Sphinx configuration?


Regards

[J Luis]

One main 'dislike' I find in the documentation is that, contrary to Matlab and R examples that have one page for each function, in julia we have lots of functions per page with short and often cryptic descriptions. Example

std(v[, region])

Compute the sample standard deviation of a vector or array v, optionally along dimensions in region.

To have longer and, VERY IMPORTANT, usage examples one need a per function page manual.

[Milan Bouchet-Valat]

Le vendredi 12 février 2016 à 04:16 -0800, J Luis a écrit :
> One main 'dislike' I find in the documentation is that, contrary to
> Matlab and R examples that have one page for each function, in julia
> we have lots of functions per page with short and often cryptic
> descriptions. Example
>
> std(v[, region])
> Compute the sample standard deviation of a vector or array v,
> optionally along dimensions in region.
>
> To have longer and, VERY IMPORTANT, usage examples one need a per
> function page manual.

It's not that common for several Julia functions to be documented on
the same page. Actually, it's probably less common than in R (have a
look at ?grep or ?read.table). But indeed the docs could be expanded in
some cases. If you make pull requests adding examples (more precisely
doctests that are run and checked when building Julia), I'm sure they
will be welcome.


Regards

[Michael Borregaard]

Maybe a good time to repost this link: https://github.com/JuliaLang/julia/blob/master/CONTRIBUTING.md#improving-documentation

As I understand it, the julia documentation format is still an evolving entity. Google-searching in R works well because of the massive number of google searches / site visits to R pages. When I started using R, during my PhD in 2006, it was almost impossible to google R functions, and there were all kinds of (not very functional) search engines to bring up R results. Today everybody just googles it. I feel completely confident that julia will have the same development, and a lot faster.

[Timothée Poisot]

A thing that works well in R is that arguments to functions have
a separate markup. When you use e.g. roxygen to write documentation, the
@params and @return elements make it clear what is what. This is
something I find lacking in Julia / Lexicon.jl

(and implementing it goes very much over my head)

This being said, I find the julia manual superior to R documentation:
the fact that all functions doing similare things are on the same page
made me realize there are better alternatives often.

t

Michael Borregaard (12/02 05:08):

> Maybe a good time to repost this link:
> https://github.com/JuliaLang/julia/blob/master/CONTRIBUTING.md#improving-documentation

> <https://www.google.com/url?q=https%3A%2F%2Fgithub.com%2FJuliaLang%2Fjulia%2Fblob%2Fmaster%2FCONTRIBUTING.md%23improving-documentation&sa=D&sntz=1&usg=AFQjCNFSu7VhGC5GE6j_5KDAKIdtnBsG4Q>

>
> As I understand it, the julia documentation format is still an evolving
> entity. Google-searching in R works well because of the massive number of
> google searches / site visits to R pages. When I started using R, during my
> PhD in 2006, it was almost impossible to google R functions, and there were
> all kinds of (not very functional) search engines to bring up R results.
> Today everybody just googles it. I feel completely confident that julia
> will have the same development, and a lot faster.
>
> Den fredag den 12. februar 2016 kl. 13.16.08 UTC+1 skrev J Luis:
> >
> > One main 'dislike' I find in the documentation is that, contrary to Matlab
> > and R examples that have one page for each function, in julia we have lots
> > of functions per page with short and often cryptic descriptions. Example
> >

> > std(*v*[, *region*])

--
Timothée Poisot, Ph.D.
Professeur adjoint
Quantitative and Computational Ecology
Department of Biological Sciences
Université de Montréal

WEB http://poisotlab.io/
TWITTER @PoisotLab

[NotSoRecentConvert]

That's similar to how I learned Matlab programming. They had similar functions listed at the bottom of each function page. Add in the forums and reverse engineering other peoples' code and you have the majority of Matlab learning experience.

[Po Choi]

Good point. I tried to use this search box in Juila manual, but get nothing.

In R and Matlab, the search would return the function sd/std.

I think, not only the "words" in Julia documentation is needed to improved, but also the search engine.

[Stefan Karpinski]

Improvements are welcomed.

[cormu...@mac.com]

On Saturday, February 13, 2016 at 1:02:50 PM UTC, Stefan Karpinski wrote:

Improvements are welcomed.

Hey Stefan. Here's my suggestion:

Until the Grand Overarching Documentation system is available, you could do worse than a custom Google search engine. This lets you add a few selected sites to index, and you don't therefore have to qualify the search with "julia" or "julialang" all the time. (Thus you won't have to keep visiting the pages of Julia Lang or seeing fractals all the time...)

I'm not a big fan of the Google, but it doesn't work too bad and I can't see too many downsides with having something like this on the main Julia site for now.

Here's a quick demo I mocked up. I'm sure someone could do something more impressive with the Google Search Engine API (https://developers.google.com/custom-search/docs/overview). 

It's currently at http://steampiano.net/julia-search/index.html.

[Stefan Karpinski]

Seems like a good idea. Thanks for looking into that.