Documentation

[tshort]

With Docile and a Base documentation system emerging (JuliaLang/julia#8791 and JuliaLang/julia#8966), it's a good time to document! We should probably wait to see what the standards will look like.

For the standard library, we can probably pull from the Modelica Standard Library. The license allows it.

[xogeny]

Tom, I've been watching this project for a while. But what I'd really like to understand (from a documentation point of view) is what the underlying assumptions are about your models. For example, you have the notion of hybrid behavior, but what about representation of synchronous events? Also, your representation of connections is very different from Modelica.

Also, is it possible to express the semantics of these things outside of a Julia context. In other words, it would be nice if there were a way of describing what was legal and what wasn't without having to lean on the Julia type systems.

My most pressing interest is in a formal specification of the flattened form but I'm also interested in the high-level representation as well.

[iraikov]

I would also be interested in at least a denotational specification of the semantics of Sims, and eventually a facility for generating C or C++ code from a flattened Sim, based on such a semantic specification. The works of Georgidze and Nillson and of Broman, on which Sims is based can be the starting point for such a specification.

[tshort]

I've opened a branch to try out documentation. I commented src/main.jl Docile style. I'll try one of the standard libraries next.

https://github.com/tshort/Sims.jl/tree/doc

[tshort]

@xogeny, I've started a design document here. It's not really a formal spec. I'm afraid the code is it for a while, but it fills in some blanks. If you have questions, that may help guide what I could fill in.

[tshort]

@iraikov, as far as generating code, I'd like to be able to generate C and JavaScript of models. Options for C include:

• Julia2C - https://groups.google.com/d/msg/julia-dev/iBsehcB62kM/JJ48wAlBilEJ
• An LLVM C backend - https://github.com/draperlaboratory/llvm-cbe

For JavaScript, one of the above may work, or maybe we can directly generate it from LLVM bitcode:

• Support compiling to JavaScript with Emscripten JuliaLang/julia#9430

That's a little different from using a flattened Sim.

[tshort]

I've documented some more in the doc branch. Overall, I'm happy with the way Docile works at the REPL. You can use ?Resistor to find help for the Resistor model. I also tried using Lexicon to generate a reference for all documented functions and models. Here are results so far:

https://tshort.github.io/Sims.jl/doc/api.html

I like the way it looks, and I really like the links to source, but it'd be better to have a way of organizing entries. Anyway, given that I'm relatively satisfied with how it integrates, and it appears to be the way that core Julia is moving, I'm planning to merge this into the master branch. Once documentation is cleaned up, I'd like to do a new release.

[iraikov]

Hi Tom,

The documentation looks pretty nice, thanks. On a somewhat related note,
do you think it is possible to use Docile for Sims models and individual
equations within a model?

On Tue, Jan 6, 2015 at 5:53 PM, Tom Short notifications@github.com wrote:

I've documented some more in the doc
https://github.com/tshort/Sims.jl/tree/doc branch. Overall, I'm happy
with the way Docile works at the REPL. You can use ?Resistor to find help
for the Resistor model. I also tried using Lexicon to generate a reference
for all documented functions and models. Here are results so far:

https://tshort.github.io/Sims.jl/doc/api.html

I like the way it looks, and I really like the links to source, but it'd
be better to have a way of organizing entries. Anyway, given that I'm
relatively satisfied with how it integrates, and it appears to be the way
that core Julia is moving, I'm planning to merge this into the master
branch. Once documentation is cleaned up, I'd like to do a new release.

—
Reply to this email directly or view it on GitHub
#10 (comment).

[tshort]

For Sims models, yes, Docile works to document those. I've done that for almost all models in the standard electrical library at least.

For individual equations in a model, no. You can currently include documentation strings in the returned model, but they aren't really tied to one equation. Plus, I'm not sure what we'd do with those doc strings. How would you look them up as in ?something at the REPL? I think the best approach is to keep models short by composing them of multiple models and document each of those.

[tshort]

Things are looking good on the documentation front. Almost everything is filled in. Docile/Lexicon works great. It gives good help in the REPL, and can spit out API-type docs for the web. Mkdocs is the best system I've found for creating documentation from Markdown. See here for the current documentation:

https://tshort.github.io/Sims.jl/

The links to code don't work because I haven't pushed to master, yet. I'll probably do that over the weekend.

In related housekeeping, I put the standard library and the examples in their own modules that are loaded with the packages. Now we have:

• Sims
• Sims.Lib
• Sims.Examples
• Sims.Examples.Basics
• Sims.Examples.Lib
• Sims.Examples.Neural

I also rearranged the directories some.

The branch I'm working on now is the mkdocs branch:

https://github.com/tshort/Sims.jl/tree/mkdocs