Documentation for QuBase

[amitjamadagni]

It would be great if we could use Docile package for documentation. As we are basing our initial attempt on Julia release version 0.3, we could use Docile as a package, this dependency would not be needed in the future as the next version of Julia has documentation in built, which is a merge of Docile. I have looked through this package which is on similar lines in terms of development depending on Julia 0.3 and using Docile HttpServer.jl. It would be great to hear some thoughts on this. (I have created a branch with initial commits which has edits in the REQUIRE as well as added a doc folder with README.md file).

[acroy]

+100 We should definitely use Docile to do internal and external documentation.

[jrevels]

I agree as well! Inline documentation rocks.

[acroy]

I haven't looked too much into this, but is there a way to have "internal" and "external" (or "expert" and "user") documentation with Docile? I am thinking of having one set of documents, which cover all the dirty details, like interface descriptions and so on. And a another set, which would basically document exported functions/types for the user.

[jrevels]

Are we going to use Lexicon.jl as well, then? I think it only supports HTML/markdown. Not a problem for me, but I know a lot of julia users prefer ReStructured text + Sphinx for documenting.

[acroy]

I guess as Docile/Lexicon are or will be the canonical way to do documentation in Julia, so other formats will also be supported if there is enough interest. For us it might be important to have some way of including equations. Is that supported by Lexicon?

[jrevels]

@acroy I don't see any specific feature for internal documentation. That would be nice to have, for sure. We might be able to configure Lexicon to save certain parts of the docs differently - I know Docile has separate a @comment macro but I'm not sure what the differences are there.

As for LaTeX support, we'd be far better off with using Sphinx, which I'm not sure will work well with Docile + Lexicon since Sphinx supports RST, not markdown. See here.

I suppose this is a more complex issue than I initially thought...

[acroy]

@jrevels : Maybe not. Lexicon and Docile manuals have sections "Manual" and "API", which would do for external and internal documentation. We just have to figure out how it works :-) Also, the Lexicon docs mention MathJax - so I guess the HTML pages can display equations.

[amitjamadagni]

There have been discussions of doxygen support for Julia. I guess that could solve the problem to a good extent. But I really dont know how much of it has gone into support for Julia.

[jrevels]

@acroy It seems I missed the MathJax support, good catch. I don't know if Lexicon's markdown parser handles nesting MathJax syntax on its own, but it seems that MkDocs has a MathJax extension, so I think we're good either way.

It seems that what Lexicon provides is a way to distinguish between documentation on exported vs. non-exported objects (see the include_internal flag for the save function). AFAIK, that means we wouldn't be able to distinguish between internal and external inline documentation for exported objects. I suppose we could simply say any "internal" documentation on exported objects should simply be left as a normal comment (or the @comment macro, depending on how Lexicon renders it), or be marked off in its own section rendered with standard markdown/not documented inline with the code.

Having different named categories like "Manual"/"API"/etc. is a feature of MkDocs/RTD in general. I don't think we want to equate "Manual"/"API" with "external"/"internal", though, since an API is generally a list of all the user-facing functions/types (apologies if I misinterpreted your wording there).

[acroy]

You are right, we shouldn't use the "API" section for internal documentation. The latter is really for us to keep track of implementation details etc. But in any case it seems we should go with Docile.jl+Lexicon.jl.