Documentation

[cscherrer]

@millerjoey @v-a-s-a The doctests PR (https://github.com/cscherrer/Soss.jl/pull/134) is now merged into dev, and I checked that Travis ran successfully (https://travis-ci.org/github/cscherrer/Soss.jl/builds/683597920). Bet they're not showing up here.

I didn't ever get this to work locally on my machine, can you describe how you were able to generate them?

[v-a-s-a]

My guess is that something is going wrong when using docs/ as the julia env when building documentation.

I was able to get these to build by replacing the env with Soss' root, i.e:

julia --project=. -e 'using Pkg; Pkg.instantiate()';
julia --color=yes --project=. docs/make.jl

I can see the sense of keeping a separate Project.toml for docs/, but will have to do some reading.experimentation to see how that works exactly.

[millerjoey]

Did help> prune end up working? If not, I wonder if that's related.

I didn't try to build the docs, but I'll give it a shot later to see if I can get it to work.

Copying @v-a-s-a's advice here to start from:

FWIW, I also ran into some namespace complaints when building docs, but not running doctests. Those were fixed by adding DocMeta.setdocmeta!(Soss, :DocTestSetup, :(using Soss); recursive=true) to the top of docs/make.jl.

[cscherrer]

@v-a-s-a that works! So I guess we need to convince Travis to do it that way :)

Also,

I can see the sense of keeping a separate Project.toml for docs/, but will have to do some reading.experimentation to see how that works exactly.

Yeah, it's possible this way of doing things could be biting us: https://github.com/JuliaLang/Pkg.jl/issues/1788

@millerjoey Yes, this works in dev:

help?> prune
search: prune isupperbounded process_running set_comparison_function product_distribution

  prune(m, xs...; simplify = true)

  Returns a model transformed by removing xs... and all variables that depend on xs.... If simplify =
  true, unneeded arguments are also removed. Use simplify = false to leave arguments unaffected.

  Examples
  ≡≡≡≡≡≡≡≡≡≡

  m = @model n begin
      α ~ Gamma()
      β ~ Gamma()
      θ ~ Beta(α,β)
      x ~ Binomial(n, θ)
  end;
  prune(m, :θ)

  # output
  @model begin
          β ~ Gamma()
          α ~ Gamma()
      end

  m = @model n begin
      α ~ Gamma()
      β ~ Gamma()
      θ ~ Beta(α,β)
      x ~ Binomial(n, θ)
  end;
  prune(m, :n)

  # output
  @model begin
          β ~ Gamma()
          α ~ Gamma()
          θ ~ Beta(α, β)
      end

As I understand, the DocMeta.setdocmeta! thing just makes it so each doctest is preceded by using Soss.

[v-a-s-a]

Awesome. It looks like we're close to having a page to play around with.

For the build: I did notice you added Pkg.develop(PackageSpec(path=pwd())); to the package instantiation and that does appear to be the correct way to use docs/Project.toml based on Documenter.jl's repo.

This is getting into the details of travis+github, and I'll have to keep reading around to understand how this works.

Some thoughts in the mean time:

• From the build log: the ENV["TRAVIS_BRANCH"] matches devbranch="master" seems to be the sticking point. Somehow the dev branch isn't getting correctly referenced.
  • Perhaps branches: only: needs to be changed in the travis config, to include the dev branch?
  • The line repo="https://github.com/cscherrer/Soss.jl/blob/{commit}{path}#L{line}", in the makedocs function can probably be removed. The docs state that this is set by an environmental variable, and perhaps the correct reference is being overwritten.
• Additionally, a lot of repo's seem to use master as a development branch, with release branches for stable versions. Some of this logic seems to be baked into documenter functions, at least as defaults.

[cscherrer]

Interesting. I always seen the stable and dev doc badges, never hit me that dev actually means master. That's kind of confusing.

In that case, maybe next we should get the docs into master. I'll start a PR to merge from dev so we can make sure we're happy with the changes.

[cscherrer]

Docs didn't build at first, because we're failing the "nightly" tests. I wouldn't worry too much about this, assuming nightly is still in flux. Actually wonder if we should consider skipping those.

Anyway, I got Travis to restart the doc build, and it completed just fine. But...

Oh wait, it worked!!!: https://cscherrer.github.io/Soss.jl/dev/

[cscherrer]

Seems just a matter of doing more of this now, so I'll close this issue :)

[v-a-s-a]

I'm going through and adding docstrings/doctests when I have some spare time. This is on the easy-to-understand functions, and mostly with the idea that something is better than nothing. There is still a lot about documentation and julia conventions that I'm learning, so feedback is welcome.