documentation: separate format1 and format2 how-to pages

[jack-oquin]

No description provided.

[jack-oquin]

Github won't let me assign myself to fix this. I guess it requires admin authority.

[jack-oquin]

Please assign this to me. I'll work on it as soon as I can find time.

[wjwwood]

That'd be great @jack-oquin, let me know if you need help or someone to review it.

[jack-oquin]

I'll certainly need reviewers, but the actual writing should not take long.

I plan to keep a copy of the format1 version, so users can refer to either. Format2 will be the recommended version, but there will still be format1 packages around for years. I think clearly separate docs will be less confusing for the readers.

[jack-oquin]

I just noticed that catkin has a separate Indigo source branch, which differs from the Groovy and Hydro branch. Is format2 only supported on Indigo, or does it work in the other branch, too?

I see there are already documentation differences between indigo-devel and groovy-devel.

[dirk-thomas]

Since the package.xml format is implemented in catkin_pkg it is independent of the catkin version. As soon as a catkin version with #619 is released format 2 can be used. The changes will also be released back into Groovy / Hydro. Then format 1 as well as 2 can be used with any current ROS distro (G, H and I).

Several things have changed between the groovy-devel and indigo-devel branch. Please compare the changelogs for details: https://github.com/ros/catkin/blob/groovy-devel/CHANGELOG.rst https://github.com/ros/catkin/blob/indigo-devel/CHANGELOG.rst

Especially deprecated functionality has been removed as well as the Eigen CMake config file. Furthermore some Python 3 specific changes have been added as well as some restrictions removed to run unit tests multi threaded. And there is an Indigo migration guide page in the docs.

[jack-oquin]

That's good.

It means we'll have to update the docs in both branches. I plan to provide an indigo-devel PR for review. Once it looks OK, we can merge those commits into groovy-devel, too.

[dirk-thomas]

That would be great. Thank you for your effort.

[jack-oquin]

Any idea where these links have moved?

WARNING: intersphinx inventory 'http://ros.org/doc/api/rospkg/html/objects.inv' not fetchable due to <class 'urllib2.HTTPError'>: HTTP Error 404: Not Found
WARNING: intersphinx inventory 'http://ros.org/doc/api/vcstools/html/objects.inv' not fetchable due to <class 'urllib2.HTTPError'>: HTTP Error 404: Not Found
WARNING: intersphinx inventory 'http://ros.org/doc/api/rosdep2/html/objects.inv' not fetchable due to <class 'urllib2.HTTPError'>: HTTP Error 404: Not Found
WARNING: intersphinx inventory 'http://ros.org/doc/api/rosinstall/html/objects.inv' not fetchable due to <class 'urllib2.HTTPError'>: HTTP Error 404: Not Found

[jack-oquin]

Where is the python_version module supposed to be defined?

[dirk-thomas]

All ROS distro independent tools are documented under http://docs.ros.org/independent/api/...

python_version module? I don't know where that should be / what it should do. May be something from a long time ago. Where did you find that reference?

[jack-oquin]

There is a python_version.rst containing an autodoc reference:

/home/joq/git/catkin/doc/dev_guide/api/python_version.rst:4: WARNING: autodoc can't import/find module 'python_version', it reported error: "No module named python_version", please check your spelling and sys.path

Maybe it's been deleted. I'll remove the reference.

[jack-oquin]

genmsg is not independent, but still used.

Should rosdep2 now be called rosdep?

[tfoote]

I don't know what the python_version.rst was supposed to refer to but most likely the python module is where it's supposed to point as that deals with the python version.

Can you provide more context in respect to genmsg? It definitely still exists and is required.

rosdep the tool is still rosdep, the module inside is the second generation and it's rosdep2. It used the different namespace to avoid collisions with the old one. We don't want to be refactoring this code without significant user benefit.

[jack-oquin]

I don't see a module named python, either. Just a directory. Where is it?

genmsg:

WARNING: intersphinx inventory 'http://docs/ros.org/indigo/api/genmsg/html/objects.inv' not fetchable due to <class 'urllib2.URLError'>: <urlopen error [Errno 111] Connection refused>
/home/joq/git/catkin/doc/dev_guide/code_generation.rst:14: WARNING: undefined label: genmsg:index (if the link has no caption the label must precede a section header)

The rosdep2 warning goes away with this change:

--- a/doc/conf.py
+++ b/doc/conf.py
@@ -217,11 +217,11 @@ latex_documents = [
 #latex_use_modindex = True

 intersphinx_mapping = {
-    'genmsg': ('http://ros.org/doc/api/genmsg/html', None),
-    'vcstools': ('http://ros.org/doc/api/vcstools/html', None),
-    'rosinstall': ('http://ros.org/doc/api/rosinstall/html', None),
-    'rospkg': ('http://ros.org/doc/api/rospkg/html', None),
-    'rosdep2': ('http://ros.org/doc/api/rosdep2/html', None),
+    'genmsg': ('http://docs/ros.org/indigo/api/genmsg/html', None),
+    'vcstools': ('http://docs.ros.org/independent/api/vcstools/html', None),
+    'rosinstall': ('http://docs.ros.org/independent/api/rosinstall/html', None),
+    'rospkg': ('http://docs.ros.org/independent/api/rospkg/html', None),
+    'rosdep': ('http://docs.ros.org/independent/api/rosdep/html', None),
     }

[dirk-thomas]

The url is obviously mailformed:

http://docs/ros.org/indigo/api/genmsg/html/objects.inv

With the correct domain it works fine for me:

http://docs.ros.org/indigo/api/genmsg/html/objects.inv
-----------^

[jack-oquin]

With that fix (and all the others) it finally builds cleanly.

I removed all reference to python_version and renamed the rosdep2 link to rosdep.

If that's OK, I'll commit those fixes as the first step.

[dirk-thomas]

If some of the changes should be considered for backporting please keep them in separate commits to easy the process.

[jack-oquin]

I think all these fixes will also apply to groovy-devel, but it is difficult to be certain.

Nothing about this mess looks easy to me.

[jack-oquin]

I have a reasonable first draft, ready for internal review:

• http://farnsworth.csres.utexas.edu/docs/catkin/html/

It's probably not ready for a full pull request review yet. I am sure we will find more to add.

[jack-oquin]

Unless there are objections, I am ready to open a pull request for these updates, and request a doc review on ros-users and the buildsystem SIG.

[wjwwood]

@jack-oquin I think we are ready for that next step.

I think the migration guide looks great. For doc depends I would just say that these dependencies are installed only for building documentation and will not get included into the binary deb's dependencies.

For the buildtool_export_depends I would just say that it behaves exactly like a build_export_depend except that in a cross-compiling scenario a non-target architecture version of this dependency is allowed. Or something to that effect, it should align with the documentation on buildtool_depend.

Otherwise everything looks good to me. +1

[jack-oquin]

@wjwwood: thanks for the comments.

Your <doc_depend> idea is good. I'll do that, perhaps adding examples for rosdoc_lite, doxygen and sphinx.

The how-to pages currently do not mention <buildtool_depend>, except to use it for catkin. Any buildtool discussion at all seems a bit advanced for these intended readers.

[dirk-thomas]

I will close this ticket since it has been addressed by the two referenced PRs.