Initial import of auto-generated tool documentation

refs #4

source/index.rst

@@ -42,6 +42,8 @@ inclusion of 3rd-party elements and complex dependency structures.
    advanced
    updating
 
+   build-generator <tools/build-generator>
+
    reference
 
    faq

source/tools.rst

@@ -0,0 +1,17 @@
+.. _tools:
+
+=======
+ Tools
+=======
+
+.. toctree::
+   :hidden:
+
+   tools/build-generator
+
+
+The following tools are available:
+
+* :ref:`build-generator <tool-build-generator>`
+
+  TODO

source/tools/build-generator-analyze.rst

@@ -0,0 +1,48 @@
+.. _command-analyze:
+
+=========
+ Analyze
+=========
+
+.. program:: analyze
+
+Synopsis
+========
+
+:samp:`build-generator {[GLOBAL-OPTIONS]} analyze [COMMAND-OPTIONS] URI-OR-DIRECTORY*`
+
+Description
+===========
+
+Analyze project repositories w.r.t. dependencies and meta-data.
+
+Analysis results are printed to the standard output stream in JSON format.
+
+.. option:: URI-OR-DIRECTORY*
+
+   Type: ``(LIST (OR PROPER-PURI PATHNAME))`` Default: ``false``
+
+   Location(s) of the project repository(ies).
+
+   For repository locations specified as URIs, the following syntax is used:
+
+   .. code-block:: sh
+
+      SCHEMA://HOST[:PORT][/PATH][#BRANCH][?scm=SCM&sub-directory=SUB-DIRECTORY]
+
+   where ``SCM`` is "git", "subversion", "mercurial" or
+   "archive", ``BRANCH`` is the branch and ``SUB-DIRECTORY`` is the
+   sub-directory within the repository that that should be analyzed. All other
+   components of the ``URI`` are passed to respective version control system.
+
+   This option can be supplied multiple times.
+
+.. option:: --nature=NATURE
+
+   Type: ``(LIST (MEMBER FREESTYLE MAVEN CMAKE ASDF ROS-PACKAGE ROS-PACKAGES))`` Default: ``false``
+
+   Nature(s) according to which the project(s) should be analyzed.
+
+   The project nature(s) is/are guessed if not specified.
+
+   This option can be supplied multiple times.

source/tools/build-generator-config.rst

@@ -0,0 +1,46 @@
+.. _command-config:
+
+========
+ Config
+========
+
+.. program:: config
+
+Synopsis
+========
+
+:samp:`build-generator {[GLOBAL-OPTIONS]} config ACTION [OPTION]`
+
+Description
+===========
+
+Describe configuration sources and the current configuration.
+
+Configuration information is merged from multiple sources (highest priority
+first):
+
+* Options specified on the commandline
+
+* Environment variables named BUILD_GENERATOR_option_name
+
+* Configuration files named build-generator.conf in the current directory,
+  ~/.config/ and /etc/. This can be changed using
+  the ``BUILD_GENERATOR_CONFIG_FILES`` environment variable.
+
+
+
+Setting the ``BUILD_GENERATOR_CONFIG_DEBUG`` environment variable to an
+arbitrary value causes debug information regarding configuration sources and
+the current configuration to printed during startup.
+
+.. option:: [OPTION]
+
+   Type: ``(OR NULL STRING)`` Default: ``false``
+
+   Name(s) of option(s) to which the action should be applied.
+
+.. option:: ACTION
+
+   Type: ``(MEMBER GET LIST TREE)`` Default: ``false``
+
+   The configuration action to perform.

source/tools/build-generator-create-jenkins-user.rst

@@ -0,0 +1,41 @@
+.. _command-create-jenkins-user:
+
+=====================
+ Create-Jenkins-User
+=====================
+
+.. program:: create-jenkins-user
+
+Synopsis
+========
+
+:samp:`build-generator {[GLOBAL-OPTIONS]} create-jenkins-user --email=EMAIL-ADDRESS --password=PASSWORD --username=USENAME DIRECTORY`
+
+Description
+===========
+
+Create a user account in a Jenkins instance.
+
+.. option:: --password=PASSWORD
+
+   Type: ``(OR NULL STRING)`` Default: ``false``
+
+   Password for the new user account.
+
+.. option:: --email=EMAIL-ADDRESS
+
+   Type: ``(OR NULL STRING)`` Default: ``false``
+
+   Email-address for the new user account.
+
+.. option:: --username=USENAME
+
+   Type: ``(OR NULL STRING)`` Default: ``false``
+
+   Username for the new user account.
+
+.. option:: DIRECTORY
+
+   Type: ``DIRECTORY-PATHNAME`` Default: ``false``
+
+   Home directory of the Jenkins instance in which the user should be created.

source/tools/build-generator-generate.rst

@@ -0,0 +1,85 @@
+.. _command-generate:
+
+==========
+ Generate
+==========
+
+.. program:: generate
+
+Synopsis
+========
+
+:samp:`build-generator {[GLOBAL-OPTIONS]} generate [COMMAND-OPTIONS] DISTRIBUTION-NAME*`
+
+Description
+===========
+
+Generate Jenkins jobs for a given distribution.
+
+.. option:: --api-token=API-TOKEN
+
+   Type: ``(OR NULL STRING)`` Default: ``false``
+
+   API token for Jenkins authentication.
+
+.. option:: --password=PASSWORD
+
+   Type: ``(OR NULL STRING)`` Default: ``false``
+
+   Password for Jenkins authentication.
+
+.. option:: --username=LOGIN
+
+   Type: ``(OR NULL STRING)`` Default: ``false``
+
+   Username for Jenkins authentication.
+
+.. option:: --base-uri=URI
+
+   Type: ``URI`` Default: ``https://localhost:8080/``
+
+   Jenkins base ``URI`` .
+
+.. option:: --delete-other-pattern=REGEX
+
+   Type: ``(OR NULL STRING)`` Default: ``false``
+
+   When deleting previously automatically generated jobs, only consider jobs
+   whose name matches the regular expression ``REGEX`` .
+
+   The default value corresponds to the common case of deleting only jobs
+   belonging to previous versions of the distribution(s) being generated, i.e.
+   the regular expression ``(DISTRIBUTION-NAME₁|DISTRIBUTION-NAME₂|…)$`` .
+
+.. option:: --delete-other
+
+   Type: ``BOOLEAN`` Default: ``false``
+
+   Delete previously automatically generated jobs when they are not re-created
+   in this generation run.
+
+.. option:: --set=VARIABLE-NAME=VALUE
+
+   Type: ``(LIST VARIABLE-ASSIGNMENT)`` Default: ``false``
+
+   Overwrite a variable after loading the distribution.
+
+   Arguments to this option have to be of the form ``VARIABLE-NAME=VALUE`` .
+
+   This option can be supplied multiple times.
+
+.. option:: --mode=MODE
+
+   Type: ``STRING`` Default: ``toolkit``
+
+   The mode according to which jobs should be generated.
+
+   Selects the set of templates stored in the templates/MODE directory.
+
+.. option:: DISTRIBUTION-NAME*
+
+   Type: ``(LIST STRING)`` Default: ``false``
+
+   Distribution recipes(s) which should be processed.
+
+   This option can be supplied multiple times.

source/tools/build-generator-help.rst

@@ -0,0 +1,23 @@
+.. _command-help:
+
+======
+ Help
+======
+
+.. program:: help
+
+Synopsis
+========
+
+:samp:`build-generator {[GLOBAL-OPTIONS]} help [COMMAND-NAME]`
+
+Description
+===========
+
+Print help either for all commands or for a given command.
+
+.. option:: [COMMAND-NAME]
+
+   Type: ``(OR NULL STRING)`` Default: ``false``
+
+   Nil or a command name for which to print help.

source/tools/build-generator-info-aspects.rst

@@ -0,0 +1,17 @@
+.. _command-info-aspects:
+
+==============
+ Info-Aspects
+==============
+
+.. program:: info-aspects
+
+Synopsis
+========
+
+:samp:`build-generator {[GLOBAL-OPTIONS]} info-aspects`
+
+Description
+===========
+
+Print information about available aspects.

source/tools/build-generator-info-variables.rst

@@ -0,0 +1,23 @@
+.. _command-info-variables:
+
+================
+ Info-Variables
+================
+
+.. program:: info-variables
+
+Synopsis
+========
+
+:samp:`build-generator {[GLOBAL-OPTIONS]} info-variables [COMMAND-OPTIONS]`
+
+Description
+===========
+
+Print information about recognized variables.
+
+.. option:: --filter=REGEX
+
+   Type: ``(OR NULL STRING FUNCTION)`` Default: ``false``
+
+   Restrict output to matching variables.