0.4.0 Docs Discussion

[jbohren]

This is for discussion of the new catkin_tools documentation: http://catkin-tools.readthedocs.org/en/latest/

[jbohren]

@dirk-thomas

Imo the "Migrating from catkin_make" pages suffers from the fact that it mixes two aspects. The step to move from catkin_make to an isolated build (like catkin_make_isolated) and then the step to catkin build. By better separating these two, their differences and similarities as well as their common problems I think a lot of previous (nd likely upcoming) questions could be avoided. Since basically users are not aware of the isolation aspect in the first place.

I think a two-step migration would help users to first get their code working with catkin_make_isolated before reporting "issues" with catkin build.

Yeah, I think this is a good idea. We should also add something along those lines to the (currently non-existent) contributing guidelines.

[j-rivero]

I've tried the installation in a clean docker Xenial system and found a problem with the bash completion:

[snip]
changing permissions of /usr/local/lib/python3.5/dist-packages/catkin_tools/jobs/commands/__pycache__/cmake.cpython-35.pyc to 644
changing permissions of /etc/bash_completion.d/catkin_tools-completion.bash to 644
changing permissions of /usr/share/zsh/site-functions/_catkin to 644
changing permissions of /usr/share/zsh/site-functions/catkin_tools-completion.bash to 644
changing permissions of /usr/local/lib/python3.5/dist-packages/catkin_tools-0.3.1-py3.5.egg-info/SOURCES.txt to 644
changing permissions of /usr/local/lib/python3.5/dist-packages/catkin_tools-0.3.1-py3.5.egg-info/dependency_links.txt to 644
changing permissions of /usr/local/lib/python3.5/dist-packages/catkin_tools-0.3.1-py3.5.egg-info/entry_points.txt to 644
changing permissions of /usr/local/lib/python3.5/dist-packages/catkin_tools-0.3.1-py3.5.egg-info/requires.txt to 644
changing permissions of /usr/local/lib/python3.5/dist-packages/catkin_tools-0.3.1-py3.5.egg-info/top_level.txt to 644
changing permissions of /usr/local/lib/python3.5/dist-packages/catkin_tools-0.3.1-py3.5.egg-info/PKG-INFO to 644
changing permissions of /usr/local/bin/catkin to 755

----------------------------------------------------------------
To enable tab completion, add the following to your '~/.bashrc':

  source /usr/local/etc/bash_completion.d/catkin_tools-completion.bash

----------------------------------------------------------------

root@87aac8196eed:/tmp/catkin_tools# source /usr/local/etc/bash_completion.d/catkin_tools-completion.bash
bash: /usr/local/etc/bash_completion.d/catkin_tools-completion.bash: No such file or directory

Note that the /usr/local prefix is not being used to install the bash_completion files (inside /etc) nor the zsh files (inside /usr/share).

[j-rivero]

I've read and play a while with the documentation, pretty clear and complete. A couple of random ideas:

• I tried to use python3. Changing the calls from python to python3 and pip to pip3 during the installation was enough. There is a good bunch of deprecation warnings affecting dependencies in python3. All commands I tried with the python3 installation were fine, except profile which is totally broken.
• I understand the separation between verbs and shell comands but maybe from the point of view of the users all both are features. While reading the docs I found the shell commands section especially useful (include the command cd and source) but these options are somehow not so visible like are the verbs specially in the index.

[jbohren]

I've tried the installation in a clean docker Xenial system and found a problem with the bash completion:

Yeah the destination of the bash completion is a known issue: #300. Based on #209 it looks like we're going to end up with separate implementations for bash and zsh, and this is something that I'd really like to see settled.

I tried to use python3. Changing the calls from python to python3 and pip to pip3 during the installation was enough. There is a good bunch of deprecation warnings affecting dependencies in python3.

Yeah, the big one being trollius, which will be replaced by asyncio in the future.

All commands I tried with the python3 installation were fine, except profile which is totally broken.

Ok, we'll make sure profile gets some unit testing for python3.

I understand the separation between verbs and shell comands but maybe from the point of view of the users all both are features. While reading the docs I found the shell commands section especially useful (include the command cd and source) but these options are somehow not so visible like are the verbs specially in the index.

Yeah, the real issue there is guaranteeing that the shell commands / verbs are made available to users. I think if we can make it so that these things are installed to the prefix in a way that doesn't require users to modify their shell profiles, they can be promoted.

[jbohren]

@dirk-thomas, @j-rivero Thanks for your feedback! We're going to improve the accessibility of the shell tools in the next release.