Let sphinx add parameter description with nested structures to documentation

[christophfroehlich]

This adds automatic documentation generation from generate_parameter_library yamls, where nested structures or __map_ parameters are used and completes #651

• It remains draft until the missing feature of the library will be implemented, see Add autodocs for nested and __map_ parameters control.ros.org#216

Binary builds will fail until generate_parameter_library is released: the multiline description generates invalid C++ code.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (9f7e9e9) 47.71% compared to head (c0b8a83) 47.81%.
Report is 6 commits behind head on master.

❗ Current head c0b8a83 differs from pull request most recent head 62b6c05. Consider uploading reports for the commit 62b6c05 to get more accurate results

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #652      +/-   ##
==========================================
+ Coverage   47.71%   47.81%   +0.10%     
==========================================
  Files          41       41              
  Lines        3871     3871              
  Branches     1833     1827       -6     
==========================================
+ Hits         1847     1851       +4     
  Misses        751      751              
+ Partials     1273     1269       -4     

Flag	Coverage Δ
unittests	47.81% <ø> (+0.10%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

see 4 files with indirect coverage changes

[mergify]

This pull request is in conflict. Could you fix it @christophfroehlich?

[fmauch]

I checked that all links point to the correct files and briefly went over the texts. I left a couple of comments on the way that in my opinion improve readability, but since I'm not a native speaker I wouldn't consider them required, hence approving.

[fmauch]

To be honest (maybe out of scope), I think having an example on what "has to be used in combination with" would be beneficial. Especially in terms of different scenarios to using map_interface_to_joint_state.

Also, explaining what leaving the lists empty means would be beneficial in my opinion.

[christophfroehlich]

If you have a text suggestion: feel free to add one. In the meantime, I opened an issue from that ;)

[christophfroehlich]

I checked that all links point to the correct files and briefly went over the texts. I left a couple of comments on the way that in my opinion improve readability, but since I'm not a native speaker I wouldn't consider them required, hence approving.

Thanks for the proof reading. I basically merged the infos from the documentation files with them of the yaml -> adding new information is actually out of scope -> I opened an issue for that.

@bmagyar can we merge and release that with the same sync than 3.7.0 of generate_parameter_library? I guess we should wait for the next one?

[mergify]

This pull request is in conflict. Could you fix it @christophfroehlich?