Docile / docstrings

[sbromberger]

OK, I'm convinced we need them. Opening this up to track.

[jpfairbanks]

Victory!

Do you want to decide on a plan for how to use the metadata dictionaries? You can put the arguments in there and maybe a reference to a benchmarking script corresponding to the function you are documenting.

[sbromberger]

No idea about any of it, @jpfairbanks - can you perhaps put together a PR for discussion?

[rlouf]

Example in PR #55 to start the discussion

[sbromberger]

I just merged #55... let's see how it goes :)

[sbromberger]

I'm not sure I like the attempt to use LaTeX/whatever:

help?> betweenness_centrality
search: betweenness_centrality

  Betweenness centrality

bc(v) =
        rac{1}{mathcal{N}}
        sum_{s
eq t
eq v}
      rac{sigma_{st}(v)}{sigma_{st}}

[rlouf]

I understand, it is not pretty... but I think it is an issue to be fixed at the Docile level. Sometimes it is necessary to document the formula you used to compute something...

[sbromberger]

Can you use markdown to do equations? Docile / new docstring will parse markdown, I think.

[rlouf]

No, there is no dedicated syntax (after all, TeX does a pretty good job). However, some markdown interpreters can recognise latex code and format it correctly (typically import mathjax.js and keep the equations between $$ $$). Here the problem is with Julia, the interpreter does seem to read what is inside docstrings (where I think it shouldn't). I'll have a better look at this, ask on Julia mailing list and may open an issue on the Julia repo.

In the meantime we can do whatever we wish, because it is likely to change anyway...

Rémi On 29 May 2015 19:01, "Seth Bromberger" notifications@github.com wrote:

Can you use markdown to do equations? Docile / new docstring will parse markdown, I think.

— Reply to this email directly or view it on GitHub https://github.com/JuliaGraphs/LightGraphs.jl/issues/54#issuecomment-106871223 .

[jpfairbanks]

You can escape the $ with \$\$ then julia will leave it alone and it will get put into the docs as a literal $$. If Docile adds latex support in the future then they will be rendered in HTML.

[sbromberger]

I think we're at the point now where we should be writing docstrings for functions. Feel free to submit PRs - I will HAPPILY merge them.

[hayd]

To answer one part of this question, if you want latex:

doc"markdown docstring for `foo` with latex: $x^2$"
function foo(...)
...
end

This is parsed (one the julia side) with Markdown.LaTeX type and should render as such (assuming mathjax is set up if it's html, or if the show methods are defined e.g. they are in lighttable/ipython).

My understanding is that the @doc macro is no longer needed, either in 0.4 or using a recent version of Docile (in both cases you can use the "line above" syntax).

[hayd]

To avoid lots of repetition between the docstrings and the docs/manual, I wonder if using https://github.com/MichaelHatherly/Lexicon.jl is the best way forward? (Essentially moving docstrings to the API section - extracted from help, and having the current markdown files (with docstrings removed) as a "manual"... ?)

I've been adding/moving docstrings for a few methods, will submit a PR.

[sbromberger]

@hayd - the only hesitation I think I have with Lexicon is what happens in 0.4 with docstrings. If there's no rework required, I think we should definitely adopt it. Your thoughts?

[hayd]

My understanding is that it's the same syntax, similarly Docile has updated to match 0.4 (on 0.3 too) i.e. (doc)string-above. No rework required. ?

[sbromberger]

OK, perfect. Would you mind doing a small demo using existing docs as a PR?

[jpfairbanks]

I just looked back in this issue and saw we were talking about Tex strings in markdown. If we use lexicon to make mardown output. If the strings contain escaped Tex strings, then we could run pandoc on that output to get pdf's or html with the math formatting right through either latex or mathjax.

[hayd]

I'm currently trying to get Lexicon up and running, will (tentatively) PR tonight or tomorrow.

[sbromberger]

Thank you very much, @hayd. I'm looking forward to seeing your PR.

@jpfairbanks I like the idea of TeX-markup docs. I hope there's a way to provide equivalent RTD content as well.

[hayd]

I meant to say: there is an open issue/roadmap for lexicon to output latex. Markdown output latex, so this shouldn't be too difficult - just laying out the document. RTD allows mathjax (latex) so that part should just work^TM.

[hayd]

Posted as #109.

[hayd]

aside from getting mathjax working for mkdocs/readthedocs, this is fixed. Modulo some tweaking.

[sbromberger]

Yup, agreed. Will close this out since we've got a couple discussions already going in the PRs.