Add an option to disable docs when building

[mjcarroll]

Currently we rebuild documentation on every build. This adds an option to disable this (default is enabled). This is helpful for development environments with repeated builds.

It can be set via colcon's cmake-args

colcon build --cmake-args -DBUILD_DOCS=OFF

Or via a defaults.yaml file:

{
  "build": {
    "merge-install": true,
    "symlink-install": true,
    "cmake-args": [
      "--no-warn-unused-cli",
      "-DCMAKE_CXX_COMPILER_LAUNCHER=ccache",
      "-DCMAKE_EXPORT_COMPILE_COMMANDS=1",
      "-DCMAKE_BUILD_TYPE=RelWithDebInfo",
      "-DBUILD_DOCS=OFF",
    ]
  }
}

Signed-off-by: Michael Carroll [email protected]

[mjcarroll]

As an example, I used a simple workspace with cmake2, common3, and math6:

• With Docs:
  • Fresh build: 140 seconds
  • Rebuild: 4.17 seconds
• Without Docs:
  • Fresh build: 139 seconds
  • Rebuild: 0.67 seconds
• Without Docs + CCache (clear cache):
  • Fresh build: 140 seconds
  • Rebuild: 0.67 seconds
• Without Docs + CCache (warm cache):
  • Fresh build: 25.9 seconds
  • Rebuild: 0.67 seconds

[chapulina]

We should document this somewhere visible. I'd recommend adding a tutorial to ign-cmake, but we first need to make sure that's deployed to the docs site (gazebosim/docs#53).

[mjcarroll]

We should document this somewhere visible. I'd recommend adding a tutorial to ign-cmake

Added information in #145