Add Documentation

[itsdfish]

I want to sketch out a plan for documentation. My plan is to have three general sections:

1. An explanation of the basic components, such as functions and structs. Some of the details are already in the code. I think it is a matter of integrating it with Documenter.jl or a different package if you have a different recommendation.

2. An in depth tutorial with the Gaussian Example showing users how to configure and run a benchmark, as well as add a new test model.

3. A results section with figures that showcase some key results.

Do you have any recommendations?

[goedman]

Hi Chris, that sounds fine. You want me to setup Documenter? Usually not hard, but tricky to get all steps right and the keys installed. I’ll also look for an easy way to copy the plots over to the correct place in the docs sub directory.

…

Sent from my iPhone

On Jul 7, 2019, at 12:06, dfish ***@***.***> wrote: I want to sketch out a plan for documentation. My plan is to have three general sections: An explanation of the basic components, such as functions and structs. Some of the details are already in the code. I think it is a matter of integrating it with Documenter.jl or a different package if you have a different recommendation. An in depth tutorial with the Gaussian Example showing users how to configure and run a benchmark, as well as add a new test model. A results section with figures that showcase some key results. Do you have any recommendations? — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

[itsdfish]

Yeah. That sounds great. I should be able to figure it out if you provide the initial setup. Thanks.

[goedman]

Hi Chris, the doc framework is in place and seems to be working (I only added a single function for testing purposes).

Oops, right now only the dev link works as we have not registered a stable version with docs.

I think we probably should register a next minor versions?

[itsdfish]

Thanks, Rob. Sure. Registering a minor version sounds like a good idea. Do I create an issue like this and increment the version to v0.0.2?

[goedman]

Correct, I usually open an issue with both in the title and body "@JuliaRegistrator register() v0.1.0"
AS this is way more than a patch release (and the package is lightyears beyond the first registered version) we should probably up the minor version number.

[JuliaRegistrator]

Error while trying to register: Version 0.0.1 already exists

[goedman]

Once tests all pass, I'll update the version number in Project.toml and try the registration again.

[itsdfish]

Hey Rob, I was wondering if you know of a way to preview the documentation? I tried making a new doc branch but I couldn't see the changes. Is there a better way to preview? Perhaps locally?

[goedman]

Not really, I just send it to Travis and it will update the master docs. Not sure if it just now did finished, I’ll check when back home. The good part is that once setup, it is fairly sturdy for the dev docs. If it has trouble completing on Travis, we can prevent the tests to run until you get a feel for how the docs get updated.

[goedman]

Aah, had a quick look, it still fails at adding a column to a DataFrame. If you want you can for now comment out all tests in runtest.jl to see the dev docs update if you push master to Travis.

[itsdfish]

Thanks. I commented out the tests, but the documentation does not update on the front github page. Any ideas?

[goedman]

Hi Chris,

Looking at the log for the documentation stage I see it fails on the updated LogDensityProblems:

379.34s$ julia --project=docs --color=yes docs/make.jl
[ Info: Default NUTS tree sampling method is set to multinomial.
WARNING: Method definition getspace(Type{#s387} where #s387<:(Turing.Inference.SMC{space, F} where F)) where {space} in module Inference at /home/travis/.julia/packages/Turing/bAh9v/src/inference/Inference.jl:92 overwritten at /home/travis/.julia/packages/Turing/bAh9v/src/inference/Inference.jl:93.
WARNING: Method definition getspace(Type{#s387} where #s387<:(Turing.Inference.PG{space, F} where F)) where {space} in module Inference at /home/travis/.julia/packages/Turing/bAh9v/src/inference/Inference.jl:92 overwritten at /home/travis/.julia/packages/Turing/bAh9v/src/inference/Inference.jl:93.
WARNING: Method definition getspace(Type{#s387} where #s387<:(Turing.Inference.PMMH{space, A} where A<:Tuple)) where {space} in module Inference at /home/travis/.julia/packages/Turing/bAh9v/src/inference/Inference.jl:92 overwritten at /home/travis/.julia/packages/Turing/bAh9v/src/inference/Inference.jl:93.
WARNING: Method definition getspace(Type{#s387} where #s387<:(Turing.Inference.IPMCMC{space, F} where F)) where {space} in module Inference at /home/travis/.julia/packages/Turing/bAh9v/src/inference/Inference.jl:92 overwritten at /home/travis/.julia/packages/Turing/bAh9v/src/inference/Inference.jl:93.
WARNING: Method definition getspace(Type{#s387} where #s387<:Turing.Inference.MH{space}) where {space} in module Inference at /home/travis/.julia/packages/Turing/bAh9v/src/inference/Inference.jl:92 overwritten at /home/travis/.julia/packages/Turing/bAh9v/src/inference/Inference.jl:93.
ERROR: LoadError: UndefVarError: ValueGradient not defined

So it never gets to updating the docs. Need to take a closer look why it is trying to load ValueGradient (no longer in LogDensityProblems).

[itsdfish]

Thanks for pointing that out. As you may have noticed, this is all new to me. Where did you find the logs and what generated them? I'm guessing this is different than the unit tests?

[goedman]

Can you get on Travis.com? You might have to logon. I used my github account to login, if I remember well. Then go to your Travis dashboard and check if you can see the MCMCBenchmark build.

[goedman]

I don't think we can easily circumvent this problem until DynamicHMC is updated. The only way I can think how to do is is to specify the previous version of LogDensityProblems in Manifest.toml but I've never tried that.

[itsdfish]

Can you get on Travis.com? You might have to logon.

Thanks. This explains why I could not find any logs! I'll sign up and try to constrain LogDensityProblems in Manifest.toml.

[itsdfish]

I am struggling to access MCMCBenchmarks via Travis. My best guess is that you might need to authorize access for me. Here is what I see after synchronizing with my Github account:

[goedman]

The update of DynamicHMC to v"1.0.6" (to match LogDensityProblems v"0.9.0") is in the queue to be merged. Hopefully it will be approved in the next couple of hours and it resolves this issue.

[itsdfish]

Excellent. Thanks for the info and adding me as a collaborator.

In terms of documentation, I was going to store figures on the repo. However, I was wondering whether you think there is a better place to host the figures.

[goedman]

Hi Chris, I think that is definitely ok. There are at least 2 ways you can opt to go: 1) prepare the pdf files off-line and move them to the docs dir or 2) generate then using Literate.jl.

[itsdfish]

I wonder what is happening with the update of DynamicHMC. Unfortunately, it is breaking quite a few things.

[goedman]

I think the issue is all 'approvers' are traveling back from JuliaCon.

[itsdfish]

Interesting. I assumed that process was automated.

[goedman]

Hi Chris,

Just noticed that the make of CmdStan 2.19.1 failed on Travis, so updated it to cmdstan 2.20.0.

I'll check if it now completes both stages or if it still has problems with LogDensityProblems 0.9.0 and why.

Rob

[itsdfish]

Thanks, Rob. There might be a separate issue with my documentation. I finished about 80%, but Travis was erroring out a few weeks ago and I was not sure how to fix it.

[goedman]

It fails in the doc stage on: ERROR: LoadError: 'purose.md' is not an existing page! which is correct. I was trying the test phase locally, so can’t commit a fix right now. Rob J Goedman [email protected]

…

On Aug 18, 2019, at 08:05, dfish ***@***.***> wrote: Thanks, Rob. There might be a separate issue with my documentation. I finished about 80%, but Travis was erroring out a few weeks ago and I was not sure how to fix it. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#28?email_source=notifications&email_token=AAAMX2AOISQSUZSVURS4FD3QFFJMHA5CNFSM4H6WH6E2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD4RAYMQ#issuecomment-522325042>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAAMX2A3W4QA66KIZLNT353QFFJMHANCNFSM4H6WH6EQ>.

[itsdfish]

Ok. I found the error and pushed the change.

Is this how you run tests locally?

[goedman]

No, I've tried Docker a few weeks ago and messed up quite a bit.

I simple mean:

] test MCMCBenchmarks

That's no good for documentation though, but I'm still having issues just running the example benchmarks.

[goedman]

Seems to have completed the docs now.

[itsdfish]

Thanks, Rob. I am making my way through the bugs with the docs and plan to run some benchmarks concurrently to report in the Benchmarks section.

Some of the tests are failing because of issues with Turing. In the meantime, I will make the tests less stringent so that they will pass in those cases as long as the benchmark runs without crashing.

[goedman]

Great Chris. I’m currently driving from Colorado to Fishers Island (NY), wii try it this weekend.

I wiil also add a bound for DynamicHMC in MCMCBenchmarks Project.toml as DHMC will be upgraded around Sep 1st and this is a breaking API change.

[itsdfish]

Hey Rob. The docs are nearly finished but I am struggling with displaying images on the Benchmark Results page. I tried to emulate the documentation for images.jl, but to no avail. Do you know what I am doing incorrectly?

[goedman]

Hi Chris, never looked at images.jl.

I know in JuaFEM they use constructs like https://github.com/KristofferC/JuAFEM.jl/blob/master/docs/src/examples/plasticity.jl to insert png files.

For StatisticalRethinking I started using Literate.jl but I'm now dropping that approach as I don't like the quality of the plots (stuff like cut-off borders). I fine just using savefig() inside scripts actually works better, but that's not what you are looking for.

I believe at one point I also used pdf files in documentation and that worked pretty ok.

[itsdfish]

After a lot of struggle, I finally got the images to show up in the docs. I'll figure out how the resize them at some point. I think its good enough to close this issue.