Submit for inclusion in ROS doc builder

[gavanderhoorn]

Is there any specific reason why this package has not been submitted for inclusion in the 3-day doc builder cycle on the farm? Searching for rosnodejs in the Kinetic distribution.yaml yields no results, and the wiki page appears to have the package header hand crafted.

I can submit the PR against ros/rosdistro, but first wanted to make sure there wasn't an actual reason that hadn't happened yet.

[gavanderhoorn]

I realise the repository is not actually a ROS pkg per se, but a very minimal package.xml could be added to add just the required / desired metadata.

[chris-smith]

That's a good question... I think @IanTheEngineer and I talked about it a while ago and ended up not including it since it's not exactly a ROS package as you pointed out - particularly, if someone apt-get installs it, the package won't really work as they might expect.

Are there particular benefits you think we'd get out of including it that we're missing? Or are we worrying too much about users installing it through apt-get, etc? The recommended way to install rosnodejs is through npm.

[gavanderhoorn]

I may not have been clear: I'm not suggesting you release the package through the buildfarm, just that you submit it for inclusion in the big documentation generation machinery.

It's perfectly possible to have packages indexed by the doc jobs without having any source builds and / or release builds enabled.

Having a package on the doc jobs would also enable automatic building of documentation, tutorials, etc. Similar to how MoveIt does this with the sphinx based docs. Those could / are then linked from the ROS wiki.

[gavanderhoorn]

Thinking about it: source builds might also be nice, as you could make use of the CI facilities of the ROS buildfarm.

I don't know how npm pkgs are normally tested, but it might be of interest.

[chris-smith]

Ah interesting. Just adding docs seems useful - how does it auto-generate docs/tutorials? Presumably there'd need to be some work to make that happen.

If we wanted to use ROS buildfarm for CI we'd need to add node and npm dependencies to it, right? I'd guess OSRF wouldn't be thrilled about that. Most npm packages I've seen are just tested through travis. We have a travis CI job but haven't gone through to set up the environment to make it run our tests - it currently just tries to build it. That's been something I've meant to do for a while...

[gavanderhoorn]

Ah interesting. Just adding docs seems useful - how does it auto-generate docs/tutorials? Presumably there'd need to be some work to make that happen.

yes. It'd be nice if the farm could write your tutorials for you ;)

re: how: rosdoc_lite.

See ros-planning/moveit_tutorials for how it is used in MoveIt.

If we wanted to use ROS buildfarm for CI we'd need to add node and npm dependencies to it, right? I'd guess OSRF wouldn't be thrilled about that.

I would think so. But there is a difference between test_depends and dependencies that get exported to actual installable packages. Why do you think "OSRF wouldn't be thrilled about that"?

Most npm packages I've seen are just tested through travis. We have a travis CI job but haven't gone through to set up the environment to make it run our tests - it currently just tries to build it. That's been something I've meant to do for a while...

Travis is also good. I just mentioned the buildfarm CI support as something that could perhaps be an additional benefit of submitting this repository for indexing.

[chris-smith]

Cool. I'm not familiar with using doxygen or sphinx for javascript. We'd have to extend them in some way or find some open source code to do so?

Assuming that's not too difficult I think including rosnodejs in the doc builder would be great.

[gavanderhoorn]

I don't have much experience with using Sphinx with js, but a quick google shows links such as Sphinx Home/Documentation/Sphinx Domains - The JavaScript Domain, sphinx-js 2.0, Use Sphinx to Generate your JS Library Docs and npmjs.com/jsdoc-sphinx: JSDoc Sphinx Template.

Those seem to indicate that (node) js support in Sphinx is already there.

[chris-smith]

sphinx-js 2.0 looks like it will work with our existing JS docs actually - they likely need to be updated and filled out more but it won't require rewriting everything.