Closed jack-oquin closed 11 years ago
tfoote
commented
11 years ago I think @eitanme 's suggestion, in the other thread, of using a symlink to the "default" version would be good.
@jack-oquin All of these documentation jobs are designed to be done against the development branch for each repo instead of the released tag. This means that you can update docs without rereleasing. And as soon as we turn on Hydro doc jobs you can link to that explicitly.
eitanme
commented
11 years ago Just thought I'd take some time to go into a bit more detail on how the documentation stuff works:
The documentation system used for the ros wiki consists of two main components. The first is rosdoc_lite which is a generic tool used to produce documentation for a given package. Detailed docs on rosdoc_lite can be found here. The second component is Willow Garage specific infrastructure to facilitate running documentation jobs. I'll focus on the WG specific infrastructure below:
The documentation jobs know what they're supposed to run on by scanning the doc folder in the rosdistro repository. Inside of the doc folder are directories for each distro that has documentation generation active. Each of these directories, in turn, has rosinstall files that specify what should be documented for a given job. The jobs are named the same as the rosinstall files and can contain any number of repositories. So, there's not necessarily a 1-1 relationship between repositories and documentation jobs, multiple repositories can be documented by one job. Basically, users can decide what they'd like to have indexed (targeted for a specific distribution) and submit pull requests for administrator approval. documentation on this can be found here.
As @tfoote mentioned above, the convention for a documentation job is to track the development branch for each repo since it has the benefit of allowing maintainers to update their documentation without re-releasing their packages. However, there's no reason that release tags can't also be documented if that's something that the ROS community decides is worthwhile down the road.
@tfoote Should I go ahead and implement the symlink option (pointing to fuerte) on the wiki? Or is that something you'd like to handle? Is there any reason for me to keep those old docs around when I do this?
A rolling design review of sorts was completed for these changes involving @tfoote, @dirk-thomas, @wmeeusse and myself, but we didn't do a great job of making the community aware of things until after the changes rolled out. For that, I do apologize. @jack-oquin Thanks for the feedback on all this, let me know if you have any other questions.
jack-oquin
commented
11 years ago Thanks for the detailed explanation, Eitan. The rosdistro update docs are good. I used them several times already, with success.
I did not fully understand the distinction you and Tully make between the release tag and the corresponding maintenance branch. That is because I do not normally create a maintenance branch until I need to make a fix to something I had previously released. Until then, the documentation depends on the release tag.
That means I need to remember to update rosdoc when making the first bug fix, assuming it requires a documentation change, which most do not. That will be easy to forget, but I am not sure where it would best be documented.
jack-oquin
commented
11 years ago While the symlink idea at least provides a persistent URL that wiki pages can use, I do not think it addresses my use case.
I usually code in the svn trunk or git master branch, making releases as I go along. I don't generally want to explicitly link to the Hydro version for new development. I would rather have a documentation link that always points to my latest development version. We used to have unstable for that. I suppose one could add that (or devel or latest) as a rosdistro subdirectory for such purposes.
I don't know whether my needs really reflect general usage, and whether they justify yet another set of documentation files.
Roslocate does have a similar concept of development sources, as opposed to specific release versions. I remain confused how the various source pointers are supposed to work in ROS. Different tools often yield different results.
tfoote
commented
11 years ago We originally had the unstable release name which was an alias for the upcoming release. However this ended up with the issue that anywhere you wrote down "unstable" it would later need to be updated to point to the specific version of the next release. Whereas if you simply write down the upcoming codename, it won't actually need changing. Links to development docs /docs under review if they don't have the version of the distro they're under development for will likely go stale.
As such I think that manually writing in the development distro's name is actually better. For if the unnamed version is updated at some point in the future the link will likely be broken at that time unless the process has been only additive.
When we turn on Hydro, the link will activate at the top of the wiki page, but until it's released groovy will still be the default. And it seems to me that the default documentation should be the development branch for the recommended release. There's another issue #15 to make the wiki macros take arguments for which version to use. And that actually needs to be generalized to all the macros.
jack-oquin
commented
11 years ago I just did some rosdistro updates tonight, and there are still no doc/hydro rosinstall files.
Should I create a new directory and put my own files there?
tfoote
commented
11 years ago @jack-oquin Go ahead and create doc/hydro if you have specific things ready for it. We're working hard to clean up the debbuild system to be easier to fork for hydro, and getting bloom tested for the upgrade.
I implemented the symlink so now it points to groovy if you don't give a distro.
There are probably hundreds of ROS wiki pages that link to auto-generated package documentation.
Formerly, that could be done with a generic link to the development documentation, like this:
Now, those links point to stale documentation versions compiled by the previous rosdoc indexer, which is no longer in use.
The new documentation indexer produces per-distro links, like these:
Those URLs resolve the automatically-generated package header references. But, their semantics seem wrong. Instead of released versions, they just point to whatever version is in the corresponding rosdistro file. I suppose that's OK, once we make it clear to all the wiki authors and package maintainers that they need to update those files appropriately, so they point to the correct version for each release.
Nevertheless, wiki authors need a way to generate their own in-line links to component documentation. Those links need to keep working across new ROS releases.
I would like to define a link to the development version of the package, typically trunk or master. That is quite useful for reviewing un-released code.
Is there any documentation for how all this works? Was there a design review when these changes were made?