examples in the documentation?

[Andreas Lobinger]

Hello,

i ran into a problem with Timer yesterday, because i interpreted the documentation in the wrong way. For complex calls like this, examples would be nice. Or let's say i come from a background where examples are kept along the documentation (incl. updating them, when something in the code changes) to have someone started on this topic.

How is the general feeling about contributing working examples to the documentation (in the sense of: putting them into the text)?

Wishing a happy day,
       Andreas

[Tony Kelman]

Sounds useful to me, but note that where the manual content lives is currently a little bit in flux. See https://github.com/JuliaLang/julia/pull/11943 and https://github.com/JuliaLang/julia/issues/11920

[Jeffrey Sarnoff]

Integrating examples is very important.

[Lucas Garron]

I know I'm just a random guy adding my +1, but good examples are very valuable for anyone new to the language, or new to programming.

Why they're important: learning to program often involves copy/pasting/twiddling with examples, and it's great to have a canonical place to copy from, especially to get used to best practices for performance or security.

As an anecdote, the documentation for Mathematica has *many* excellent examples that are easy to find and fiddle with (from within Mathematica, actually). They're how I turned from a mathematician into a programmer. Here's a sample function documentation for function fitting (rendered on the web, so not copyable from there).

G'fun,

»Lucas

[René Donner]

I think it would be fantastic. One of the best features of Matlab is that for every single function there is at least one real world code example. Copy & pasting these really kickstarts your code.

If there is a decision to do this I would definitely be able to contribute time to this effort.

[Tim Holy]

I'm supportive of this plan.

--Tim

[Andreas Lobinger]

Hello colleague,

On Friday, July 31, 2015 at 11:23:47 AM UTC+2, Tim Holy wrote:

I'm supportive of this plan.

Which plan? Just open an issue? Even the @doc macro isn't seen around these days although it exists now for some time...

[Thiago Peixoto]

I am able to help with that too.

--
-----------------------------------------------------------------------------------------
Thiago Peixoto
Majoring in Computer Science
Institute of Computing - Federal University of Alagoas, Brazil

[Jeffrey Sarnoff]

The plan is that it become simple to supply an example and then have it be included in the docs or returned for alteration.

[Tero Frondelius]

Hi all,

I just added my first example to the Julia documentation: https://github.com/JuliaLang/julia/pull/12279#issuecomment-126058754.

I just wanted to point out that I should have made it as doctest. Doctests are working and can be tested this way: go to julia folder and type `make -C doc doctest`.

From the above pull request discussion you can also find a link to the example of doctest.

Br,

Tero 

[Jeffrey Sarnoff]

I am happy to see this stir, and up for tilling this field.  Tero -- I just looked at your example, and all that went alongside it.
Rather than use that as a template, would you write here the specific steps that you find useful. And if there are links,
include them here.  Assume your reader does not know the process. Thanks.

[Tero Frondelius]

We have had this same discussion in JuliaFEM, hopefully we will eventually have a very comprehensive documentation of the contributing process: https://github.com/JuliaFEM/JuliaFEM.jl/pull/54.

When you want to contribute an example(s) to Julia's documentation, the process is following:

1) Create an account or sign in to GitHub https://github.com/ (my user name is TeroFrondelius and it's used from here on as an example)

2) Install Git to your computer https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

3) Fork Julia to your repository https://github.com/JuliaLang/julia 

4) Clone and build Julia from source to your computer (from your forked repository) https://github.com/JuliaLang/julia#source-download-and-compilation

     `git clone g...@github.com:TeroFrondelius/julia.git`

     `cd julia`

     `make -j 8`

5) Find the function documentation, which you want to write an example. Let's say you want to write more examples for round() function http://julia.readthedocs.org/en/latest/stdlib/math/#Base.round: 

     `find -name *.rst | xargs grep "round("` (this will help you to locate the ./doc/stdlib/math.rst file where the round() function documentation is written. 

6) edit the ./doc/stdlib/math.rst with your favorite editor (i.e. Juno http://junolab.org/)

        .. doctest::

            julia> round(1.7)

            2.0

7) run the doctest using the command `make -C doc doctest` (and make sure your new doctest will pass)

8) Add updated files using command `git add ./doc/stdlib/math.rst` 

9) Commit the files to your repository and add a description message:

      git commit -m "new doctest for round()"

10) git push g...@github.com:TeroFrondelius/julia.git

11) At your repository (https://github.com/TeroFrondelius/julia), create a pull request

I hope this helps someone. Please correct if you see a mistake in my process. 

[Jeffrey Sarnoff]

That helps me. Thank you Tero.

[Tony Kelman]

After step 4, but before step 5, you should run `git checkout -b newbranchname`. It's always best to use a separate branch for each pull request, in case conflicts occur. You can essentially leave master on your fork alone, and only work from named branches. Since your fork will get out of date quickly, in step 4 it's probably better to clone from upstream JuliaLang/julia, but add a remote for your own fork `git remote add TeroFrondelius https://TeroFro...@github.com/TeroFrondelius/julia.git` that you can push to.

[Jeffrey Sarnoff]

Also helpful ... thanks. I have been tripping over permutations of ways that might (and did not) accomplish this,

an adjacent task.  Writing a module, I want to have github's memory working for me and as author I prefer

the master copy reside with me locally and github stay well synced.  What seqence brings that about/?

On Friday, July 31, 2015 at 4:18:15 PM UTC-4, Tony Kelman wrote:

After step 4, but before step 5, you should run `git checkout -b newbranchname`. It's always best to use a separate branch for each pull request, in case conflicts occur. You can essentially leave master on your fork alone, and only work from named branches. Since your fork will get out of date quickly, in step 4 it's probably better to clone from upstream JuliaLang/julia, but add a remote for your own fork `git remote add TeroFrondelius https://TeroFrondelius@github.com/TeroFrondelius/julia.git` that you can push to.

[Tony Kelman]

Just do git push to github frequently, that's all. You could write scripts or aliases etc if you really want to automate pushing to github immediately on every commit, but sometimes that's not what you want to do.

[Jeffrey Sarnoff]

ok -- and +1 the value of clear writing.