Documentation tied to version of compas pkg.

Documentation tied to version of compas pkg.

Problem description

I’d guess that the majority of users are installing compas from pypi or conda which means that they are installing the repo at a tagged commit. If they want to view the documentation online however they will see documentation from the most recent commit, which could cause confusion.

So the correct (version specific) documentation will be available in the installed package but not online.

Proposed solution

I think it would be good to consider a system that allows documentation tied to tagged commits.

Two examples with both works with Sphinx would be:

• sphinxcontrib-versioning
• ReadTheDocs

Sphinxcontrib-versioning could probably work with our current Invoke solution while a solution like ReadTheDocs would mean having the docs built and hosted by another service.

If there’s interest I’d happily help making this change.

[tetov]

pasting here from a parallel discussion:

the “problem” is indeed related to this. however, in the specific case of delaunay and trimesh, the api docs do correspond to the current conda package version (0.7.2) but the examples and tutorials reflect an older state. not sure how these get generated…

context: we encountered in the MAS compas introduction, that the example mesh-delaunay-from-points and mesh-remeshing both import from compas.topology intsead of compas.geometry and compas.datastructures respectively.

I’m currently updating the examples (docs/examples/) to make them work with v0.7.2. I’m not sure the examples as they are set up now could be tied to versions… I’ll have a look.

[yck011522]

Generic Ping.

I see that compas_fab have this versioning already. I don’t know the implementation details but maybe we can use the same system? https://github.com/compas-dev/compas_fab/pull/196

Maybe @gonzalocasas have some experience?