Open mikepurvis opened 8 years ago
Mike,
I was out of town Monday and Tuesday, sorry for the delayed response.
I don't have much personal experience with epydoc, mostly being a sphinx and doxygen user. I probably have less idea what's going on than you do. So, I'll ask some simple questions in hopes they might stimulate us to come up with answers or at least further experiments:
I recently noticed that rosdoc_lite is unable to document itself (#65), due to a missing doc dependency on python-catkin-sphinx
(ros-infrastructure/catkin-sphinx#6). That's not relevant to epydoc, but maybe there is a similar undeclared dependency for that path?
Basically, the build farm uses rosdoc_lite in strange and specially-crafted ways. Building it locally is unlikely to yield exactly the same results. :frowning:
Okay, have poked and prodded a bit more, looks like a cwd issue. The following works as expected:
rosinstall_generator rosdoc_lite rospy --rosdistro indigo --deps --tar > test.rosinstall
rosinstall src test.rosinstall -j8
catkin build rospy rosdoc_lite
source devel/setup.bash
pushd src/ros_comm/rospy
rosdoc_lite . -o ../../../doc
popd
So, this can be worked around, but IMO it is a bug in rosdoc_lite.
Yeah, rosdoc_lite
expects the current directory to be at the top of the package. That's annoying, and not clearly documented.
It does not seem appropriate to change that behavior now, but I suppose we could add something like a --chdir
option, so you could do this:
rosdoc_lite --chdir=src/ros_comm/rospy
$ rosdoc_lite -h
Usage: rosdoc_lite [options] [package_path]
Options:
-h, --help show this help message and exit
-q, --quiet Suppress doxygen errors.
-o OUTPUT_DIRECTORY The directory to write documentation to.
-t TAGFILE, --tagfile=TAGFILE
Path to tag configuration file for Doxygen cross
referencing support. Ex: /home/user/tagfiles_list.yaml
-g GENERATE_TAGFILE, --generate_tagfile=GENERATE_TAGFILE
If specified, will generate a doxygen tagfile in this
location. Ex: /home/user/tags/package.tag
The package_path
arg seems to strongly imply that you can specify the path to the package you wish to generate documentation for, but it turns out that the only valid value for this field is .
? That seems absurd, particularly when generating in another folder works fine for Sphinx and Doxygen— only epydoc has this issue.
I agree that the documentation implies different behavior. But, I hesitate to change how it works after all these years.
What do you suggest? Just chdir
to the optional package_path
?
That seems to be how the Sphinx plugin handles things:
Ah! That's why it only fails with epydoc.
In that case, a similar patch to the epydoc plugin seems appropriate and more-consistent.
It seems that unlike with Sphinx and Doxygen, successfully generating epydoc depends on the package being built and on the
PYTHONPATH
. And the epydoc docs clearly build successfully in ros_buildfarm (eg), so I'm struggling to understand where this goes wrong:Result:
The weirdest thing of all, though, is that if I manually execute the epydoc command outside of rosdoc_lite's mangling of the PYTHONPATH, it totally succeeds:
I tried not building rospy, and also building it in a separate workspace with catkin_make rather than catkin_tools, and using the install rather than devel space— no dice. What am I doing wrong here?