Clarify "Install iCub software from source using the robotology-superbuild on Linux"

[traversaro]

Feedback appearing from working on this with @Uboldi80 :

• It is not clear if the initial link to robotology-superbuild needs to be followed or not.
• It is not documented anywhere that if on an icub setup, the superbuild needs to be download in /usr/local/src

[traversaro]

The fact that <YYYY.MM> means that that git checkout v<2021.05> needs to be done and not git checkout v<2021.05>

[traversaro]

Another pitfall is that the docs link directly to how to install the superbuild linux section, jumping the part https://github.com/robotology/robotology-superbuild#clone-the-repo in which it is explained that is necessary as a first step to do:

git config --global user.name FirstName LastName
git config --global user.email user@email.domain

[traversaro]

It is not documented anywhere that if on an icub setup, the superbuild needs to be download in /usr/local/src

This is actually not true, as it is documented as part of the "Installation on specific systems on iCub setup" section, see https://github.com/icub-tech-iit/documentation/blob/92d0eb1e9c715b16d75b2a8b8d17ee7ecb3a03be/mkdocs.yml#L138 . However, with @Uboldi80 we did not found that section, so I think there are a few problems with that section now:

• It is not linked at the end of the "install OS" documentation for the different machines, so it is easy not to find it.
• It only contains detailed instructions for the icub-head, and it should be expanded to include the documentation for pc104 and iCub Console and iCub Console Server.

[traversaro]

Another pitfall is that the docs link directly to how to install the superbuild linux section, jumping the part https://github.com/robotology/robotology-superbuild#clone-the-repo in which it is explained that is necessary as a first step to do:

git config --global user.name FirstName LastName
git config --global user.email user@email.domain

Related issue: robotology/ycm-cmake-modules#455 .