Documentation tied to version of compas pkg.

[tetov]

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.

[tomvanmele]

hi anton,

yes, that is indeed an unsolved problem that causes confusion. especially when we make backwards incompatible changes to the API.

as far as i know, it is not possible to use your own theme with RTD, so i would prefer the sphinxcontrib-versioning solution.

would be helpful indeed if you could propose a solution.

thanks,
tom

[tetov]

Hi Tom!

I see. Yeah, RTD only allows its own theme or the standard Sphinx theme.

I will try to get the versioning-extension to work in the coming week. There's is some questions regarding the maintenance of the project, see sphinx-contrib/sphinxcontrib-versioning#59, but there seems to be people interested and keen to keep it going.

EDIT
Here's an example of sphinxcontrib-versioning in use, source. Adding it here to give an example, and as a note to self.

[tetov]

Easiest would be to add the version selection like mockup above. Would that be a good solution?

And make the current version bold or in a different color.

[tomvanmele]

if clicking on the version number switches the docs to the corresponding version, then that is great :)

[worbit]

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.

[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.

[tomvanmele]

the examples will need some manual maintenance. there is no way around this. we should clearly mention that people have to report broken examples on the issue tracker...

[tetov]

Examples updated, see PR #343
Found a tutorial that needs updating but might be better for someone else to look at since I don't really understand the tutorial yet haha. See issue #344

[tetov]

I haven't forgotten this, I've tried to get it working but no luck so far. See linked issue for more details.

sphinx-contrib/sphinxcontrib-versioning#70

[tetov]

Documentation will reflect latest release, PR #396. Closing.

[tetov]

Adding this as a note to future self, we would need to amend old tagged commits to add sphinxcontrib_versioning to the conf.py extension array.
sphinx-contrib/sphinxcontrib-versioning#70 (comment)

[tetov]

This might be something to look at again, I've been following the development of a new sphinx plugin, sphinx-multiversion.

I can do some test, maybe this weekend..

[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? compas-dev/compas_fab#196

Maybe @gonzalocasas have some experience?