Best and fastest sources for function information

New to Julia
,
1

Below are a list of questions I am constantly searching for answers to on Google when coding in Julia. What is the best and fastest way to answer each?

  1. What is the syntax for this function?
  2. What output should I expect from this function?
  3. Do my function inputs need to be a certain type (multiple arguments, a tuple, or a vector)?
  4. What does the source code of this function look like?
  5. What functions are available in this package?
  6. What is the website for documentation and tutorials on this package?
  7. Where is the webpage for documentation on this particular function?

I know about ? in the REPL already, but I find it difficult to scroll up through all the plain text in that small window of my IDE to pinpoint precisely what I am looking for. I can usually find the information faster by searching StackOverflow. I think I am spoiled by Matlabā€™s doc function which opens all the information you could possibly want in your web browser. The syntax and methods are listed at the top for quick reference and hyperlinked to more detailed explanations and examples further down (e.g. max). I find Matlabā€™s approach to be very efficient and would love to see it copied by Julia. But in the meantime, what is the current approach?

2 Likes
2

Try Zeal.

2 Likes
3

Which IDE do you use? In VS Code you get a popup with the docs for functions when you hover over them. I primarily use ? in the REPL and that works fine for me but I also have a gigantic monitor so maybe that helps. You can also right-click a function in VS Code and click ā€˜Go to definitionā€¦ā€™ (or something like that) and it will actually pull up the source code.

2 Likes
4

Hi @Nathan_Boyer :wave:

Well, you know the obvious. Matlab is a commercial company with armies of paid developers making all this stuff seem magical. Julia is an open-source project maintained mostly by enthusiastic volunteers so you need to manage your expectations a little bit :slight_smile:

Nevertheless, some of what you are looking for is available.

4 . What does the source code of this function look like?
7 . Where is the webpage for documentation on this particular function?

No one promised a web page for every function :sweat_smile:

However, all registered packages are publicly available so you can find their repo. If you want one location, you might find JuliaHub useful:

One thing you can do to see the source code for a function would be

@edit somefunction(somearg)

but I often just use

@which somefunction(somearg)

and then look it up in the respective repo rather than open it in an editor.

  1. What is the website for documentation and tutorials on this package?

Wow. High expectations much? :smiley:

If there are tutorials, they would normally be linked in the packages README on Github or whereever the repo is hosted, but not every package has tutorials. Again, JuliaHub may be useful for this.

  1. What functions are available in this package?

Although not perfect, one way to get a rough cut at this is names. With default arguments (in v1.5 - Did this change?), names gives you a list of exported methods. Iā€™d probably recommend

names(SomePackage, imported=true)

1 . What is the syntax for this function?
3 . Do my function inputs need to be a certain type (multiple arguments, a tuple, or a vector)?

Since Julia is built on multiple dispatch, a function can have hundreds of methods.

One way to see the available methods for a function is:

methods(somefunc)
  1. What output should I expect from this function?

With multiple dispatch, the answer to this question can depend on the inputs :slight_smile:

In a nutshell, @which is your friend. I use it all the time.

Another good one to be aware of is methodswith.

I hope this helps :slight_smile:

[Edit: I second @mthelm85ā€™s suggestions regarding VS Code :+1:]

4 Likes
5

I am using Atom Juno currently with plans to switch to VS Code if I can ever get my head wrapped around it. (I tried and failed once already. :expressionless:) Iā€™ll give it another go and look into those features. I learned Matlab, then Fortran, and now Julia. I donā€™t have any IDE experience besides the built-in one for Matlab and Vim for Fortran, so I often have a difficult time just figuring out how to get the code to run in modern IDEs. :woozy_face:

1 Like
6

If you havenā€™t seen then, youā€™ve gotta check out these two videos from JuliaCon:

:slight_smile:

2 Likes
7

I know that asking for in-depth, high-quality documentation for every function in existence is too much to ask for open source software. I am more asking for a centralized collection of what is available and for easy access to it through the REPL.

The most popular packages like Base, Plots, DataFrames, etc. have dedicated websites with tutorials. It would be nice if Julia encouraged a standard format for these websites, and for the package hosts to provide a list of hyperlinks for use with something like a doc command. It could just send back a generic ā€œWebpage not yet available. Search on JuliaHub.com for more information.ā€ if unavailable.

(I still have a lot of videos to catch up on from JuliaCon!)

1 Like
8

Since Julia is built on multiple dispatch, a function can have hundreds of methods.

With multiple dispatch, the answer to this question can depend on the inputs :slight_smile:

The options you present are definitely helpful, but some of the output is unreadable with multiple dispatch if you donā€™t already know what you are looking for. The advice I often get to just ā€œread the documentationā€ isnā€™t very helpful when the documentation is so varied in breadth, format, and location. It can take hours to find a simple answer. JuliaHub does seem to at least be a good starting point for a lot of those questions. I just wish there was a better way to jump to information rather than combing through walls of text.

9

One thing I like in Python which works less well in Julia is the printing of docstrings. If I type help(foo) or foo? in Python/IPython it opens a page viewer that starts at the top of the docstring, and you can scroll down through it. When you press q, the view closes and disappears.

In the Julia REPL, the docstring is printed, and you skip to the bottom of it, so you have to scroll back up, and if itā€™s a long docstring with many methods, itā€™s easy to scroll past the beginning. The start is also often where the most relevant info is.

Would it be hard to print and skip to the start of the docstring? Maybe I can even configure the viewer myself, and I just donā€™t realize?

5 Likes
10

Some related issue/PRs about docstring display in the REPL:

https://github.com/JuliaLang/julia/pull/34226

https://github.com/JuliaLang/julia/issues/36460

Help is probably needed now that the first feature has arrived in v1.5 to gate more of the especially verbose parts of docstrings behind an # Extended help header. In the broader package ecosystem a well as in Base/StdLib. Iā€™m sure PRs would be appreciated.

1 Like
11

You can use this function instead of the help repl mode if you have less installed on your system:

doc(f) = open(io -> print(io, Base.Docs.doc(f)), `less`, "w", stdout)

Try it with e.g. doc(findfirst). Itā€™s a stopgap, but it should do what you want.

EDIT: or, in case youā€™re a windows user:

doc(f) = open(io -> print(io, Base.Docs.doc(f)), `more`, "w", stdout)

(Untested, but it maybe probably works fine most of the time)

1 Like
12

Atom has a documentation browser, so you shouldnā€™t have to worry about scrolling in the REPL? Plus it shows a popup with the function syntax and types for different available methods:

image
image827Ɨ131 17.3 KB

Here you see leftjoin expects two AbstractDataFrames as its input, plus you get the start of the docstring. Clicking on ā€œMoreā€¦ā€ then opens up the documentation browser:

image
image824Ɨ678 42.2 KB

So Iā€™d think (1) and (3) are covered in Juno (if you want to switch to VS Code, thereā€™s currently no docs browser but this is a planned feature).

(2) can be tricky as the output of a function can depend on the inputs and their types, but normally Iā€™d also think that the docstring - shown in the docs browser - is your best bet for answering this question.

Other have already highlighted the super convenient @which and @edit macros, Iā€™ll add that the docs broswer in Juno also includes the output of @which as a clickable link at the bottom of the docs:

image
image826Ɨ69 3.48 KB

Number (5) is a bit tricky as the ā€œnamesā€ here can be a bit overwhelming when compared to the Python/OOP world of myobject.<tab> display of only functions that operate on the object of interest. I second Ericā€™s point, but again would add that Junoā€™s docs browser can be of assistance: type the name of the package

image

and then ā€œMoreā€¦ā€ will again take you to the documentation pane:

image
image844Ɨ693 31.6 KB

Which also has links to (6), the documentation, if they are available on GitHub. (6) and (7) though canā€™t be answered in general Iā€™d think as different packages take different approaches.

3 Likes
13

Well-documented packages have

  1. docstrings for the exposed API, which serve as a quick reminders for syntax,
  2. more detailed generated documentation, usually linked from the Git repository front page,
  3. tutorial-like documentation, either as part of the docs or as interactive notebooks.

Packages which are less mature may be missing some of the above, in which case you can look up the source (export lists, function call signatures), ask in issues or here.

YMMV, but I found Matlab docs particularly horrible for third party libraries. I often ran into

A, B, C = somefunction(D, E, 'flag', 'otherflag')

where C and otherflag was not documented as a possible combination, just tagged on at some point because someone found it useful, then I had to wade through a forest of branches doing various things based on nargin and nargout to figure out whatā€™s going on.

At least in idiomatic Julia code, it is reasonably easy to figure out whatā€™s happening, roughly, based on the source. Then you just make a PR adding a docstring to make it easier for the next person.

3 Likes