docs: updating after merging #293

- regenerating examples and cli interfaces
- switching all text to sentence-per-line
- adding scripts and documentation for regenerating examples
- moving --locate-extra-shell-verbs to locate verb
- adding details on linked develspace

catkin_tools/commands/catkin.py

@@ -155,8 +155,6 @@ def catkin_main(sysargs):
         help='Forces catkin to output in color, even when the terminal does not appear to support it.')
     add('--no-color', action='store_true', default=False,
         help='Forces catkin to not use color in the output, regardless of the detect terminal type.')
-    add('--locate-extra-shell-verbs', action='store_true',
-        help='Returns the full path of the file to source for extra shell verbs, then exits.')
 
     # Generate a list of verbs available
     verbs = list_verbs()
@@ -211,14 +209,6 @@ def catkin_main(sysargs):
     # Do verb alias expansion
     sysargs = expand_verb_aliases(sysargs, verb_aliases)
 
-    # Check for --locate-extra-shell-verbs
-    for arg in sysargs:
-        if arg == '--locate-extra-shell-verbs':
-            this_dir = os.path.dirname(__file__)
-            shell_verbs = os.path.join(this_dir, '..', 'verbs', 'catkin_shell_verbs.bash')
-            print(os.path.normpath(shell_verbs))
-            sys.exit(0)
-
     # Determine the verb, splitting arguments into pre and post verb
     verb = None
     pre_verb_args = []

catkin_tools/verbs/catkin_locate/cli.py

@@ -72,13 +72,33 @@ def prepare_arguments(parser):
     add('package', metavar='PACKAGE', nargs='?',
         help="The name of a package to locate.")
 
+    special_group = parser.add_argument_group(
+        'Special Directories',
+        'Get the absolute path to a special catkin location')
+    add = special_group.add_argument
+    add('--shell-verbs', action='store_true',
+        help="Get the path to the shell verbs script.")
+    add('--examples', action='store_true',
+        help="Get the path to the examples directory.")
+
     return parser
 
 
 def main(opts):
     # Initialize dictionary version of opts namespace
     opts_vars = vars(opts) if opts else {}
 
+    # Check for special locations
+    root_resource_path = os.path.join(os.path.dirname(__file__), '..', '..')
+    if opts.shell_verbs:
+        shell_verbs = os.path.join(root_resource_path, 'verbs', 'catkin_shell_verbs.bash')
+        print(os.path.normpath(shell_verbs))
+        sys.exit(0)
+    elif opts.examples:
+        shell_verbs = os.path.join(root_resource_path, '..', 'docs', 'examples')
+        print(os.path.normpath(shell_verbs))
+        sys.exit(0)
+
     # Get the workspace (either the given directory or the enclosing ws)
     workspace_hint = opts_vars.get('workspace', None) or os.getcwd()
     workspace = find_enclosing_workspace(workspace_hint)

docs/advanced/linked_develspace.rst

@@ -0,0 +1,20 @@
+Linked Devel Space
+==================
+
+In addition to the ``merged`` and ``isolated`` **devel space** layouts provided by ``catkin_make`` and ``catkin_make_isolated``, respectively, ``catkin_tools`` provides a default ``linked`` layout which enables robust cleaning of individual packages from a workspace.
+It does this by building each package into its own hidden FHS tree, and then symbolically linking all products into the unified **devel space** which is specified in the workspace configuration.
+
+When building with a ``linked`` layout, Catkin packages are built into FHS trees stored in the ``.private`` hidden directory at the root of the **devel space**.
+Within this directory is a directory for each package in the workspace.
+
+Setup File Generation
+^^^^^^^^^^^^^^^^^^^^^
+
+In the ``merged`` layout, every package writes and then over-writes the colliding setup files in the root of the **devel space**.
+This leads to race conditions and other problems when trying to parallelize building.
+With he ``linked`` layout, however, only one package generates these files, and this is either a built-in "prebuild" package, or if it exists in the workspace, the ``catkin`` CMake package, itself.
+
+.catkin File Generation
+^^^^^^^^^^^^^^^^^^^^^^^
+
+When using the ``linked`` layout, ``catkin_tools`` is also responsible for managing the ``.catkin`` file in the root of the **devel space**.

docs/build_types.rst

@@ -67,8 +67,6 @@ Build Stages
  First           Subsequent    Description
 ==============  ============  ==================================================
  ``mkdir``                    | Create package build space if it doesn't exist.
-----------------------------  --------------------------------------------------
- ``envgen``                   | Generate environment setup file for building.
 ----------------------------  --------------------------------------------------
  ``cmake``       ``check``    | Run CMake configure step **once** for the
                               | first build and the ``cmake_check_build_system``

docs/cheat_sheet.rst

@@ -80,13 +80,13 @@ Cleaning Build Products
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 Blow away the build, devel, and install spaces (if they exist):
-  - ``catkin clean -a``
+  - ``catkin clean``
 
 ... or just the **build space**:
   - ``catkin clean --build``
 
-... or just delete the `CMakeCache.txt` files for each package:
-  - ``catkin clean --cmake-cache``
+... or just clean a single package:
+  - ``catkin clean PKGNAME``
 
 ... or just delete the build directories for packages which have been disabled or removed:
   - ``catkin clean --orphans``

docs/examples/README.md

@@ -0,0 +1,45 @@
+Documentation Examples
+======================
+
+This document explains how to run examples and generate all static text and
+asciinema videos.
+
+## Prerequisites
+
+* [perl](http://perl.org)
+* [asciinema](http://asciinema.org)
+* [rosinstall\_generator](https://github.com/vcstools/wstool)
+* [wstool](https://github.com/vcstools/wstool)
+* [catkin](https://github.com/ros/catkin)
+
+## Generating All Examples
+
+All examples must be run from the examples directory.
+
+```bash
+./quickstart_ws/all.bash
+./failure_ws/all.bash
+./ros_tutorials_ws/all.bash
+```
+
+## Scripts
+
+### slowrun
+
+The `slowrun` script executes a script line by line, echoing characters to the
+console with a delay, as if they were being typed.
+
+Optional arguments:
+
+* `--buffer` -- buffer and delay printing of each line from the output from subcommands
+
+### slowrecord
+
+The `slowrecord` script executes a script line by line with `slowrun`, but also
+spawns a `urxvt` terminal with a specific size, and records the commands with
+`asciinema`.
+
+Optional arguments:
+
+* `--check` -- check interactively before uploading
+* `--tall` -- use a taller window for recording

docs/examples/failure_ws/all.bash

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+
+SLOWRECORD=$(pwd)/slowrecord
+WS=/tmp/failure_ws
+
+pushd `dirname $0`
+
+rm -rf $WS
+
+source /opt/ros/indigo/setup.bash
+bash 0_init.bash
+$SLOWRECORD --check --tall --buffer 1_build_warning.bash
+$SLOWRECORD --check --tall --buffer 2_build_err.bash
+
+popd

docs/examples/quickstart_ws/1_prebuild.out

@@ -0,0 +1,13 @@
+.
+├── .catkin_tools
+│   ├── CATKIN_IGNORE
+│   ├── profiles
+│   ├── README
+│   └── VERSION
+└── src
+    ├── pkg_a
+    ├── pkg_b
+    ├── pkg_c
+    └── pkg_d
+
+7 directories, 3 files