Documentation

[blahah]

We need docs, and at last, Julia has a package that supports literate programming.

We should:

• implement literate programming across the whole module using Docile.jl
• generate documentation from the Docile annotations using Lexicon.jl
• ideally, generate a readTheDocs interface

To-do list:

• [x] Add Docile
• [x] Use it to annotate the Phylo submodule
• [x] Add Lexicon
• [x] Use it to write documentation for the Phylo submodule, integrating the Docile annotations
• [x] annotate the Seq submodule
• [x] write documentation for the Seq submodule
• [x] write general documentation for the whole library

[prcastro]

The new documentation system feels more appropriate now

[TransGirlCodes]

Forgive me for being dumb, I've had a look in the Julia manual to see if theres a section on documentation and I don't see anything. Can you point me to where I can find info and usage of the new documentation system? I'll make sure Phylo is changed to this system over the xmas holidays.

[prcastro]

Here is the related pull request, but only works with 0.4. Since Bio.jl will probably be ready only after Julia's v0.4 release, I think it wouldn't be nice to start implementing it.

But maybe we should wait until the final syntax arrive.

[TransGirlCodes]

The current state of documentation for the phyllo module I'm working on - on my fork is using lexicon and docile, to generate mkdocs documentation, and it also works with Julia's '?' operator.

[prcastro]

With Compat.jl, I think we can implement documentation on v0.3. Can I start to documenting the Seq module?

[blahah]

I previously made some docs for Phylo (https://github.com/Blahah/Bio.jl/tree/phylodocs/doc) - did you build on these @Ward9250 or start from scratch? I suspect my docs are all out of date by now. But I did make a simple pretty page that I thought might form the basis of our website :)

@brk00 The new system looks a lot like Docile - except, ironically, less well documented. Does it allow annotation of arguments like this: https://github.com/Blahah/Bio.jl/blob/phylodocs/src/phylo/typedefs.jl#L49-L73 ?

[TransGirlCodes]

I've been using v0.4 to write my code and I do git pulls and makes most days out of habit for any repo I have on my machines. Docile and Lexicon has been working for me for Phylo, I did redo the documentation to make it work, but it is still what @Blahah wrote plus a few modifications to reflect one or two changes, and the addition of documentation for stuff that didn't exist when the docs were first written. Check out my phylo v1 branch to see what I've done with the docs - I liked the idea of generating a mkdocs page/site. But then this evening I was randomly growing Github and found @dcjones made something called Judo and the Gadfly doc site looks really really nice.

[dcjones]

@brk00 It would be awesome if you wanted to work on this.

Does it allow annotation of arguments like this: https://github.com/Blahah/Bio.jl/blob/phylodocs/src/phylo/typedefs.jl#L49-L73 ?

I haven't really kept up with this, but it seems like neither Docile nor Base @doc support that syntax anymore. We should probably decide on a convention for documenting arguments and return types within the markdown string. Something like:

# Arguments
  * `foo`: something
  * `bar`: something else entirely

# Returns
Nuclear launch codes encoded in an `Uint64`.

Judo is a different approach to documentation that I wrote before Docile came along which is based more on external documentation. It's being used in a few places, e.g. Gadfly, Compose, JuMPerR, Reactive. Ultimately I'd like to make Judo work with Docile to combine external expository documentation with inline API documentation using docstrings. So I think we should push forward with docstrings, and we can decide if Judo would be useful later.

[TransGirlCodes]

Indeed they don't support that syntax, your docstrings count as markdown though so I managed to get a similar format just by using markdown. This is largely what I've done - arguments are a Descriptive list (I think I called them parameters).

[TransGirlCodes]

Just took a look at Reactive, looks very cool, makes me wonder if there's an application here that will allow a Julia equivalent to the Shiny framework.

[prcastro]

We should probably decide on a convention for documenting arguments and return types within the markdown string.

That's true. I propose the following:

• function signature
• explanation of what the function do
• examples* (optional)
• arguments*
• returns*

The parts marked with * would wave a title, e.g

# Examples

julia> length(dna"ACTG")
   4

[dcjones]

@brk00 Than sounds good to me. I don't think we need to include the function signature in the docstring. If you're using Lexicon, it's shown automatically. Also, I would put "examples" after "arguments" and "returns", like unix man pages.

@Ward9250 Have you played around with Interact.jl? It's only useable from IJulia/Jupyter, but it's pretty slick. Shashi is working on a really powerful system for making web-based UIs for Julia now. Currently called Canvas.jl.

[TransGirlCodes]

I have not played with Interact.jl yet. I've been meaning to get into IPython a lot more when I can find time to learn how it works. I'll take a look at Canvas.jl. On an unrelated note @dcjones I stumbled on your peakolator repository earlier and I wondered if it is finished / usable yet? If so I would like to try it for a potential applied use I'll PM you about as it's unrelated to this thread.

[blahah]

OK so just to summarise, we will have a convention for documentation that looks like this:

Description of the function.

# Arguments
  * `foo`: something
  * `bar`: something else entirely

# Examples
 * `length(dna"ACTG") # -> 4`

# Returns
Nuclear launch codes encoded in an `Uint64`.

Examples and Returns are optional.

If there are no objections, I will start using this convention.

[TransGirlCodes]

I have no objections, this will go into the Contributing.md so everyone will know how to do it?

[prcastro]

Given the way Julia presents markdown on REPL, I prefer to use something like:

Description of the function

### Arguments
* `a`: Some argument
* `b`: Other argument

### Returns
The object it returns

### Side effects (not sure about this name)
Print something to screen, modify variable `x`

### Examples
Some examples

Know what the function returns may be useful to understand some of the examples, therefore I'd also prefer to put Returns before the Examples.

[blahah]

Good points, I agree. Also we should state argument and return types in a consistent way, like:

### Arguments
- `x::Type`: Some argument

### Returns
`Type`: Some explanation.

[TransGirlCodes]

Should we document if a method may possibly do a throw?

[blahah]

Definitely.

[prcastro]

I think this is mostly done now.