Turing.jl: Move documentation to their repos?

[devmotion]

As mentioned in https://github.com/TuringLang/Turing.jl/pull/1428#issuecomment-734347791, there are some issues with the current setup of the documentation. It is decoupled from the repos where it actually belongs to, which leads to redundant, contradicting and outdated documentation (as e.g. in the case of AbstractMCMC - the documentation on turing.ml is outdated and the interface is only described correctly in the README in the AbstractMCMC repo). Additionally, users of DynamicPPL or AbstractMCMC do not know about the documentation and developers of these packages can't properly update the documentation when adding features to their repos apart from changing the README if Turing still uses the previous version. I assume it also leads to the impression that all these packages are designed specifically for Turing which is (not always) the case.

One suggestion would be to move documentation to the repos to which it belongs (similar to what is done in JuliaGaussianProcesses) and only link to these documentations from the Turing webpage. One could link to the documentation of the version that is used by Turing.jl, but it would still be possible for developers to update it when they add new features/change the interface/etc. and users of these packages that do not use Turing could still read the latest version of the docs.

[torfjelde]

I very much support this suggestion :+1:

[cpfiffer]

Yeah, this is currently the goal -- I'm working on separating out all the website stuff to another repo (https://github.com/turinglang/turing.ml) and only leaving the individual guides as .md files in Turing. All the other repos should probably follow, and serve their own documentation sites. For the moment, we can have everyone just use vanilla Documenter.jl, but in time we will probably have something that looks like a template that makes a doc site look like Turing's main page.

[devmotion]

Now that the turing.ml repo exists, I guess we can move on with this issue? It seems currently everything is built and handled in turing.ml but it would be good to distribute the build process over the different repos and remove the versioning from turing.ml, similar to JuliaGaussianProcesses where the static parts live in https://github.com/JuliaGaussianProcesses/JuliaGaussianProcesses.github.io and each package such as https://github.com/JuliaGaussianProcesses/KernelFunctions.jl is responsible for its docs. If the tutorials are switched over to Weave and use their own project environments I guess even they can be separated from all other parts (and even Turing).

[cpfiffer]

I actually don't think any of the building should happen within a repo, partly because it's too much of an administrative headache. All each of the repos should have is a set of markdown documents in docs/src that contains what they want to see in their doc site.

[yebai]

I actually don't think any of the building should happen within a repo, partly because it's too much of an administrative headache. All each of the repos should have is a set of markdown documents in docs/src that contains what they want to see in their doc site.

yes, I'm with Cameron on this matter. In general, each Turing library should have its own docs folder made of markdown files, but the building should be handled by a single build script in turing.ml if possible.

[rikhuijzer]

Would it be appreciated if setup documenter for MCMCChains? I would like to migrate https://github.com/rikhuijzer/TuringPlots.jl like @devmotion advised me to do on Slack, but the docs is a bit of a blocker. To include my package in MCMCChains, I would like to create a Documenter.jl website where one page is dedicated to plotting via Gadfly and looks like https://rikhuijzer.github.io/TuringPlots.jl/dev/.

[cpfiffer]

I wouldn't be opposed to that.