[Documentation] [TitleIndex] [WordIndex

Only released in EOL distros:  

rosorg: rosbrowse | rosdoc_rosorg

Package Summary

Version of rosdoc for the ROS.org documenation.

rosorg: rosbrowse | rosdoc_rosorg

Package Summary

Version of rosdoc for the ROS.org documenation.

Overview

rosdoc_rosorg is an extension of the rosdoc tool to support generating resources necessary for the ROS.org web site. This includes various indexes used by wiki macros and other tools.

This package is not intended for general use, though people interested in setting up their own indexing infrastructure are welcome to contact the author for help setting this up on their site.

Version-controlled files

Rosdoc_rosorg as well as ros_release depend on several files stored in version control of those projects, some of which are backups of generation results, others are maintained manually.

Generated files not under version control

generated by rosdoc_rosorg --rosbrowse, all used by rosbrowse, from distro*.yaml (I guess always the latest & greatest?)

rosorg.png

Graphical overview of scripts and data files. Simple rectangles represent data files. When given with path, those are under version control. Other shapes are (python) scripts. scripts consume files and produce files. --options show how to pass an input to a script, or what option is required to produce output.

scripts

create_distro_index.py

Usage: create_distro_index.py <distro> <filename>

Writes into <filename> a yaml dict:

{'repos': safe_repo_index, 'stacks': stack_index, 'distro_name': distro_name}

based on rospkg.distro.load_distro(), which in turn reads files from code.ros.org/svn/release..../<distro>.rosdistro

The transformation does not add any information, it just applies rules to generate uris. So this generated all the .yaml files that were placed into rosorg_rosdoc/index.

generate_index.py

usage: generate_index.py [options] <output-file>

writes into rosinstall <out-file> (default repos.rosinstall), based on rospkg.distro and https://code.ros.org/svn/ros/stacks/rosorg/trunk/rosdoc_rosorg/repos.list

Source file contains lists of pairs (uri: foo, name: bar.rosinstall) where each bar.rosinstall lists repositories from which to check out sources.

rosdoc_rosorg

Usage: rosdoc_rosorg --repos=<filename> [options] [packages...]

Options:
  -h, --help            show this help message and exit
  -n NAME, --name=NAME  Name for documentation set
  -q, --quiet           Suppress some errors
  --paths=PATHS         package paths to document
  -o OUTPUT_DIRECTORY   directory to write documentation to
  --upload=RSYNC_TARGET
                        rsync target argument
  --repos=ROSBROWSE_REPOS_FILE
                        rosinstall file with repos list for determining repository names/roots
  --distro-index=DISTRO_INDEX_FILE
                        distro index for determining repository contents for
                        binary installs
  --checkout=CHECKOUT_DIR
                        path to checkout directory for repos file
  --test                run in test mode
  --rosbrowse           run rosbrowse indexer instead

--repos is a required option, it takes a rosinstall-like file with additional "meta" tags to declare membership of an SCM repository to a larger "repo" (e.g. all lab-wide stacks).

--distro-index is an optional file (e.g. rosdoc_rosorg/distro-*.yaml) :

distro_name: foo
repos: 
  repo-name: [stackname1, stackname2]
stacks: 
  stackname1: {version: ver1,
               repo: repo1,
               rules: {git: &id001 {uri: foo,
                                    dev-branch: bar,
                                    distro-tag: dist1,
                                    release-tag: rtag1} } }
  stackname2: {version: ver1,
               repo: repo1,
               rules: {git: *id001 } }

Which contains redundant structural data (repo <-> stack). Also it contains yaml references (*0001 points to &0001) The code is parsed by core.py, where the Repo class represents one stack (not Repo), and a repo is represented as an aggregate name of a stack.

--checkout allows to pass a location where stacks have been checked out locally, instead of being apt-get installed released stacks.

--rosbrowse is a switch.

If it is off, the script will use rosdoc to generate API docs for all stacks and packages discovered using roslib.rospack, and also create for each repo listed in the file given in --repos option (and distro-index option), manifest.yaml, stack.yaml and repo.yaml for each repo discovered by parsing the given files.

If --rosbrowse is given, instead of the repo.yaml, stack.yaml and manifest.yaml, the megamanifest and megastack are generated as megamanifest.xml, megamanifest.yaml and megastack.yaml. Those can be uploaded to:

The --rosbrowse option generating mega* files ignores the list of packages given as arguments, those only affect doc generation.

Basically the --rosbrowse switch should be a separate command / script.

Other rosdoc_rosorg options relate to the original rosdoc script.

install_distro_index

usage: install_distro_index.py <filename>

calls sudo apt-get install with each stackname mentioned in the YAML file dict 'stacks'.


2024-03-23 12:55