Reformat docstrings for SCM

Tidy up the docstrings to use consistent formatting, move inline
examples to tests and add urls for additional information on source code
web browsers.

Change-Id: I696389516dbd4e0960986666e32fab93e515710e

7 files changed, 208 insertions, 172 deletions

diff --git a/jenkins_jobs/modules/scm.py b/jenkins_jobs/modules/scm.py
index 17bc2f05..97160926 100644
--- a/jenkins_jobs/modules/scm.py
+++ b/jenkins_jobs/modules/scm.py
@@ -50,23 +50,25 @@ def git(parser, xml_parent, data):
 
     :arg str url: URL of the git repository
     :arg str credentials-id: ID of credential to use to connect, which is the
-      last field(a 32-digit hexadecimal code) of the path of URL visible after
-      you clicked the credential under Jenkins Global credentials. (optional)
-    :arg str refspec: refspec to fetch (default '+refs/heads/\*:refs/remotes/\
-remoteName/\*')
+        last field (a 32-digit hexadecimal code) of the path of URL visible
+        after you clicked the credential under Jenkins Global credentials.
+        (optional)
+    :arg str refspec: refspec to fetch (default
+        '+refs/heads/\*:refs/remotes/remoteName/\*')
     :arg str name: name to fetch (default 'origin')
     :arg list(str) remotes: list of remotes to set up (optional, only needed if
-      multiple remotes need to be set up)
-
-        :Remote: * **url** (`string`) - url of remote repo
-                 * **refspec** (`string`) - refspec to fetch (optional)
-                 * **credentials-id** - ID of credential to use to connect,
-                   which is the last field of the path of URL
-                   (a 32-digit hexadecimal code) visible after you clicked
-                   credential under Jenkins Global credentials. (optional)
+        multiple remotes need to be set up)
+
+        :Remote:
+            * **url** (`string`) - url of remote repo
+            * **refspec** (`string`) - refspec to fetch (optional)
+            * **credentials-id** - ID of credential to use to connect, which
+              is the last field of the path of URL (a 32-digit hexadecimal
+              code) visible after you clicked credential under Jenkins Global
+              credentials. (optional)
     :arg list(str) branches: list of branch specifiers to build (default '**')
     :arg list(str) excluded-users: list of users to ignore revisions from
-      when polling for changes. (if polling is enabled, optional)
+        when polling for changes. (if polling is enabled, optional)
     :arg list(str) included-regions: list of file/folders to include (optional)
     :arg list(str) excluded-regions: list of file/folders to exclude (optional)
     :arg str local-branch: Checkout/merge to local branch (optional)
@@ -81,7 +83,7 @@ remoteName/\*')
             * **fast-forward-mode** (`string`) - merge fast-forward mode.
               Can be one of 'FF', 'FF_ONLY' or 'NO_FF'. (default 'FF')
     :arg str basedir: location relative to the workspace root to clone to
-             (default: workspace)
+        (default workspace)
     :arg bool skip-tag: Skip tagging (default false)
     :arg bool shallow-clone: Perform shallow clone (default false)
     :arg bool prune: Prune remote branches (default false)
@@ -100,98 +102,86 @@ remoteName/\*')
         .. deprecated:: 1.1.1. Please use submodule extension.
 
     :arg bool use-author: Use author rather than committer in Jenkin's build
-      changeset (default false)
+        changeset (default false)
     :arg str git-tool: The name of the Git installation to use (default
-      'Default')
+        'Default')
     :arg str reference-repo: Path of the reference repo to use during clone
-      (optional)
+        (optional)
     :arg str scm-name: The unique scm name for this Git SCM (optional)
     :arg bool ignore-notify: Ignore notifyCommit URL accesses (default false)
-    :arg str browser: what repository browser to use (default '(Auto)')
+    :arg str browser: what repository browser to use.
+
+        :browsers supported:
+            * **auto** - (default)
+            * **assemblaweb** - https://www.assembla.com/
+            * **bitbucketweb** - https://www.bitbucket.org/
+            * **cgit** - http://git.zx2c4.com/cgit/about/
+            * **fisheye** - https://www.atlassian.com/software/fisheye
+            * **gitblit** - http://gitblit.com/
+            * **githubweb** - https://github.com/
+            * **gitiles** - https://code.google.com/p/gitiles/
+            * **gitlab** - https://about.gitlab.com/
+            * **gitlist** - http://gitlist.org/
+            * **gitoriousweb** - https://gitorious.org/
+            * **gitweb** - http://git-scm.com/docs/gitweb
+            * **kiln** - https://www.fogcreek.com/kiln/
+            * **microsoft\-tfs\-2013** - |tfs_2013|
+            * **phabricator** - http://phabricator.org/
+            * **redmineweb** - http://www.redmine.org/
+            * **rhodecode** - https://rhodecode.com/
+            * **stash** - https://www.atlassian.com/software/stash
+            * **viewgit** - http://viewgit.fealdia.org/
     :arg str browser-url: url for the repository browser (required if browser
-      is not '(Auto)', no default)
+        is not 'auto', no default)
     :arg str browser-version: version of the repository browser (GitLab only,
-      default '0.0')
+        default '0.0')
     :arg str project-name: project name in Gitblit and ViewGit repobrowser
-      (optional)
+        (optional)
     :arg str repo-name: repository name in phabricator repobrowser (optional)
-    :arg str choosing-strategy: Jenkins class for selecting what to build
-      (default 'default')
+    :arg str choosing-strategy: Jenkins class for selecting what to build.
+        Can be one of `default`, `inverse`, or `gerrit` (default 'default')
     :arg str git-config-name: Configure name for Git clone (optional)
     :arg str git-config-email: Configure email for Git clone (optional)
 
-
     :extensions:
-        :arg dict changelog-against:
-            :changelog-against:
-                * **remote** (`string`) - name of repo that contains branch to
-                  create changelog against (default 'origin')
-                * **branch** (`string`) - name of the branch to create
-                  changelog against (default 'master')
-
-        :arg dict clean:
-            :clean:
-                * **after** (`bool`) - Clean the workspace after checkout
-                * **before** (`bool`) - Clean the workspace before checkout
-
-        :arg list(str) ignore-commits-with-messages: Revisions committed with
-            messages matching these patterns will be ignored. (optional)
-
-        :arg bool force-polling-using-workspace: Force polling using workspace
-            (default false)
-
-        :arg dict sparse-checkout:
-            :sparse-checkout:
-                * **paths** (`list`) - List of paths to sparse checkout.
-                  (optional)
-
-        :arg dict submodule:
-            :submodule:
-                * **disable** (`bool`) - By disabling support for submodules
-                  you can still keep using basic git plugin functionality
-                  and just have Jenkins to ignore submodules completely as
-                  if they didn't exist.
-                * **recursive** (`bool`) - Retrieve all submodules recursively
-                  (uses '--recursive' option which requires git>=1.6.5)
-                * **tracking** (`bool`) - Retrieve the tip of the configured
-                  branch in .gitmodules (Uses '--remote' option which
-                  requires git>=1.8.2)
-                * **timeout** (`int`) - Specify a timeout (in minutes) for
-                  submodules operations (default: 10).
-
-        :arg str timeout: Timeout for git commands in minutes (optional)
-        :arg bool wipe-workspace: Wipe out workspace before build
-          (default true)
-
-    :browser values:
-        :auto:
-        :assemblaweb:
-        :bitbucketweb:
-        :cgit:
-        :fisheye:
-        :gitblit:
-        :githubweb:
-        :gitiles:
-        :gitlab:
-        :gitlist:
-        :gitoriousweb:
-        :gitweb:
-        :kiln:
-        :microsoft-tfs-2013:
-        :phabricator:
-        :redmineweb:
-        :rhodecode:
-        :stash:
-        :viewgit:
-
-    :choosing-strategy values:
-        :default:
-        :inverse:
-        :gerrit:
+
+        * **changelog-against** (`dict`)
+            * **remote** (`string`) - name of repo that contains branch to
+              create changelog against (default 'origin')
+            * **branch** (`string`) - name of the branch to create changelog
+              against (default 'master')
+        * **clean** (`dict`)
+            * **after** (`bool`) - Clean the workspace after checkout
+            * **before** (`bool`) - Clean the workspace before checkout
+        * **ignore-commits-with-messages** (`list(str)`) - Revisions committed
+          with messages matching these patterns will be ignored. (optional)
+        * **force-polling-using-workspace** (`bool`) - Force polling using
+          workspace (default false)
+        * **sparse-checkout** (`dict`)
+            * **paths** (`list`) - List of paths to sparse checkout. (optional)
+        * **submodule** (`dict`)
+            * **disable** (`bool`) - By disabling support for submodules you
+              can still keep using basic git plugin functionality and just have
+              Jenkins to ignore submodules completely as if they didn't exist.
+            * **recursive** (`bool`) - Retrieve all submodules recursively
+              (uses '--recursive' option which requires git>=1.6.5)
+            * **tracking** (`bool`) - Retrieve the tip of the configured
+              branch in .gitmodules (Uses '\-\-remote' option which requires
+              git>=1.8.2)
+            * **timeout** (`int`) - Specify a timeout (in minutes) for
+              submodules operations (default: 10).
+        * **timeout** (`str`) - Timeout for git commands in minutes (optional)
+        * **wipe-workspace** (`bool`) - Wipe out workspace before build
+            (default true)
+
 
     Example:
 
     .. literalinclude:: /../../tests/scm/fixtures/git001.yaml
+
+    .. |tfs_2013| replace::
+        https://www.visualstudio.com/en-us/products/tfs-overview-vs.aspx
+
     """
     logger = logging.getLogger("%s:git" % __name__)
 
@@ -441,21 +431,21 @@ def repo(parser, xml_parent, data):
     :arg str manifest-url: URL of the repo manifest
     :arg str manifest-branch: The branch of the manifest to use (optional)
     :arg str manifest-file: Initial manifest file to use when initialising
-             (optional)
+        (optional)
     :arg str manifest-group: Only retrieve those projects in the manifest
-             tagged with the provided group name (optional)
+        tagged with the provided group name (optional)
     :arg str destination-dir: Location relative to the workspace root to clone
-             under (optional)
+        under (optional)
     :arg str repo-url: custom url to retrieve the repo application (optional)
     :arg str mirror-dir: Path to mirror directory to reference when
-             initialising (optional)
+        initialising (optional)
     :arg int jobs: Number of projects to fetch simultaneously (default 0)
     :arg bool current-branch: Fetch only the current branch from the server
-              (default true)
+        (default true)
     :arg bool quiet: Make repo more quiet
-              (default true)
+        (default true)
     :arg str local-manifest: Contents of .repo/local_manifest.xml, written
-             prior to calling sync (optional)
+        prior to calling sync (optional)
 
     Example:
 
@@ -507,11 +497,11 @@ def store(parser, xml_parent, data):
     :arg str script: name of the Store script to run
     :arg str repository: name of the Store repository
     :arg str version-regex: regular expression that specifies which pundle
-             versions should be considered (optional)
+        versions should be considered (optional)
     :arg str minimum-blessing: minimum blessing level to consider (optional)
     :arg str parcel-builder-file: name of the file to generate as input to
-             a later parcel building step (optional - if not specified, then
-             no parcel builder file will be generated)
+        a later parcel building step (optional - if not specified, then no
+        parcel builder file will be generated)
     :arg list pundles:
 
         :(package or bundle): (`dict`): A package or bundle to check
@@ -566,44 +556,46 @@ def svn(parser, xml_parent, data):
 
     :arg str url: URL of the svn repository
     :arg str basedir: location relative to the workspace root to checkout to
-      (default '.')
+        (default '.')
     :arg str credentials-id: optional argument to specify the ID of credentials
-      to use
+        to use
     :arg str repo-depth: Repository depth. Can be one of 'infinity', 'empty',
-      'files', 'immediates' or 'unknown'. (default 'infinity')
+        'files', 'immediates' or 'unknown'. (default 'infinity')
     :arg bool ignore-externals: Ignore Externals. (default false)
     :arg str workspaceupdater: optional argument to specify
-      how to update the workspace (default wipeworkspace)
+    :arg str workspaceupdater: optional argument to specify how to update the
+        workspace (default wipeworkspace)
+
+        :supported values:
+             * **wipeworkspace** - deletes the workspace before checking out
+             * **revertupdate** - do an svn revert then an svn update
+             * **emulateclean** - delete unversioned/ignored files then update
+             * **update** - do an svn update as much as possible
+
     :arg list(str) excluded-users: list of users to ignore revisions from
-      when polling for changes (if polling is enabled; parameter is optional)
+        when polling for changes (if polling is enabled; parameter is optional)
     :arg list(str) included-regions: list of file/folders to include
-      (optional)
+        (optional)
     :arg list(str) excluded-regions: list of file/folders to exclude (optional)
     :arg list(str) excluded-commit-messages: list of commit messages to exclude
-      (optional)
+        (optional)
     :arg str exclusion-revprop-name: revision svn-property to ignore (optional)
     :arg bool ignore-property-changes-on-directories: ignore svn-property only
-      changes of directories (default false)
+        changes of directories (default false)
     :arg bool filter-changelog: If set Jenkins will apply the same inclusion
-      and exclusion patterns for displaying changelog entries as it does for
-      polling for changes (default false)
+        and exclusion patterns for displaying changelog entries as it does for
+        polling for changes (default false)
     :arg list repos: list of repositories to checkout (optional)
     :arg str viewvc-url: URL of the svn web interface (optional)
 
-      :Repo: * **url** (`str`) -- URL for the repository
-             * **basedir** (`str`) -- Location relative to the workspace
-               root to checkout to (default '.')
-             * **credentials-id** - optional ID of credentials to use
-             * **repo-depth** - Repository depth. Can be one of 'infinity',
-               'empty', 'files', 'immediates' or 'unknown'.
-               (default 'infinity')
-             * **ignore-externals** - Ignore Externals. (default false)
-
-    :workspaceupdater values:
-             :wipeworkspace: - deletes the workspace before checking out
-             :revertupdate:  - do an svn revert then an svn update
-             :emulateclean:  - delete unversioned/ignored files then update
-             :update:        - do an svn update as much as possible
+        :Repo:
+            * **url** (`str`) -- URL for the repository
+            * **basedir** (`str`) -- Location relative to the workspace root
+              to checkout to (default '.')
+            * **credentials-id** - optional ID of credentials to use
+            * **repo-depth** - Repository depth. Can be one of 'infinity',
+              'empty', 'files', 'immediates' or 'unknown'. (default 'infinity')
+            * **ignore-externals** - Ignore Externals. (default false)
 
     Multiple repos example:
 
@@ -743,37 +735,11 @@ def tfs(parser, xml_parent, data):
               uses server-url)
 
 
-    Examples::
-
-      scm:
-        - tfs:
-           server-url: "tfs.company.com"
-           project-path: "$/myproject"
-           login: "mydomain\\\jane"
-           use-update: false
-           local-path: "../foo/"
-           workspace: "Hudson-${JOB_NAME}"
-           web-access:
-               - web-url: "http://TFSMachine:8080"
-
-      scm:
-        - tfs:
-           server-url: "tfs.company.com"
-           project-path: "$/myproject"
-           login: "jane@mydomain"
-           use-update: false
-           local-path: "../foo/"
-           workspace: "Hudson-${JOB_NAME}"
-           web-access:
-
-      scm:
-        - tfs:
-           server-url: "tfs.company.com"
-           project-path: "$/myproject"
-           login: "mydomain\\\jane"
-           use-update: false
-           local-path: "../foo/"
-           workspace: "Hudson-${JOB_NAME}"
+    Examples:
+
+    .. literalinclude:: /../../tests/scm/fixtures/tfs-001.yaml
+
+    .. literalinclude:: /../../tests/scm/fixtures/tfs-002.yaml
 
     """
 
@@ -856,28 +822,31 @@ def hg(self, xml_parent, data):
     :arg str credentials-id: ID of credentials to use to connect (optional)
     :arg str revision-type: revision type to use (default 'branch')
     :arg str revision: the branch or tag name you would like to track
-      (default 'default')
+        (default 'default')
     :arg list(str) modules: reduce unnecessary builds by specifying a list of
-      "modules" within the repository. A module is a directory name within the
-      repository that this project lives in. (default '')
+        "modules" within the repository. A module is a directory name within
+        the repository that this project lives in. (default '')
     :arg bool clean: wipe any local modifications or untracked files in the
-      repository checkout (default false)
+        repository checkout (default false)
     :arg str subdir: check out the Mercurial repository into this
-      subdirectory of the job's workspace (optional)
+        subdirectory of the job's workspace (optional)
     :arg bool disable-changelog: do not calculate the Mercurial changelog
-      for each build (default false)
-    :arg str browser: what repository browser to use (default 'auto')
+        for each build (default false)
+    :arg str browser: what repository browser to use
+
+        :browsers supported:
+            * **auto** - (default)
+            * **bitbucketweb** - https://www.bitbucket.org/
+            * **fisheye** - https://www.atlassian.com/software/fisheye
+            * **googlecode** - https://code.google.com/
+            * **hgweb** - https://www.selenic.com/hg/help/hgweb
+            * **kilnhg** - https://www.fogcreek.com/kiln/
+            * **rhodecode** - https://rhodecode.com/ (versions >= 1.2)
+            * **rhodecode-pre-1.2.0** - https://rhodecode.com/ (versions < 1.2)
+
     :arg str browser-url: url for the repository browser
-      (required if browser is set)
-
-    :browser values:
-        :fisheye:
-        :bitbucketweb:
-        :googlecode:
-        :hgweb:
-        :kilnhg:
-        :rhodecode:
-        :rhodecodelegacy:
+        (required if browser is set)
+
 
     Example:
 
diff --git a/tests/scm/fixtures/tfs-001.xml b/tests/scm/fixtures/tfs-001.xml
new file mode 100644
index 00000000..7e100f94
--- /dev/null
+++ b/tests/scm/fixtures/tfs-001.xml
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="utf-8"?>
+<project>
+  <scm class="hudson.plugins.tfs.TeamFoundationServerScm">
+    <serverUrl>tfs.company.com</serverUrl>
+    <projectPath>$/myproject</projectPath>
+    <localPath>../foo/</localPath>
+    <workspaceName>Hudson-${JOB_NAME}</workspaceName>
+    <userPassword/>
+    <userName>mydomain\\jane</userName>
+    <useUpdate>False</useUpdate>
+    <repositoryBrowser class="hudson.plugins.tfs.browsers.TeamSystemWebAccessBrowser">
+      <url>http://TFSMachine:8080</url>
+    </repositoryBrowser>
+  </scm>
+</project>
diff --git a/tests/scm/fixtures/tfs-001.yaml b/tests/scm/fixtures/tfs-001.yaml
new file mode 100644
index 00000000..df12b505
--- /dev/null
+++ b/tests/scm/fixtures/tfs-001.yaml
@@ -0,0 +1,10 @@
+scm:
+  - tfs:
+      server-url: "tfs.company.com"
+      project-path: "$/myproject"
+      login: "mydomain\\\\jane"
+      use-update: false
+      local-path: "../foo/"
+      workspace: "Hudson-${JOB_NAME}"
+      web-access:
+        - web-url: "http://TFSMachine:8080"
\ No newline at end of file
diff --git a/tests/scm/fixtures/tfs-002.xml b/tests/scm/fixtures/tfs-002.xml
new file mode 100644
index 00000000..0ac942a3
--- /dev/null
+++ b/tests/scm/fixtures/tfs-002.xml
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="utf-8"?>
+<project>
+  <scm class="hudson.plugins.tfs.TeamFoundationServerScm">
+    <serverUrl>tfs.company.com</serverUrl>
+    <projectPath>$/myproject</projectPath>
+    <localPath>../foo/</localPath>
+    <workspaceName>Hudson-${JOB_NAME}</workspaceName>
+    <userPassword/>
+    <userName>jane@mydomain</userName>
+    <useUpdate>False</useUpdate>
+    <repositoryBrowser class="hudson.plugins.tfs.browsers.TeamSystemWebAccessBrowser"/>
+  </scm>
+</project>
diff --git a/tests/scm/fixtures/tfs-002.yaml b/tests/scm/fixtures/tfs-002.yaml
new file mode 100644
index 00000000..b59081ad
--- /dev/null
+++ b/tests/scm/fixtures/tfs-002.yaml
@@ -0,0 +1,9 @@
+scm:
+  - tfs:
+      server-url: "tfs.company.com"
+      project-path: "$/myproject"
+      login: "jane@mydomain"
+      use-update: false
+      local-path: "../foo/"
+      workspace: "Hudson-${JOB_NAME}"
+      web-access:
diff --git a/tests/scm/fixtures/tfs-003.xml b/tests/scm/fixtures/tfs-003.xml
new file mode 100644
index 00000000..c045b053
--- /dev/null
+++ b/tests/scm/fixtures/tfs-003.xml
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<project>
+  <scm class="hudson.plugins.tfs.TeamFoundationServerScm">
+    <serverUrl>tfs.company.com</serverUrl>
+    <projectPath>$/myproject</projectPath>
+    <localPath>../foo/</localPath>
+    <workspaceName>Hudson-${JOB_NAME}</workspaceName>
+    <userPassword/>
+    <userName>mydomain\\jane</userName>
+    <useUpdate>False</useUpdate>
+  </scm>
+</project>
diff --git a/tests/scm/fixtures/tfs-003.yaml b/tests/scm/fixtures/tfs-003.yaml
new file mode 100644
index 00000000..fea65471
--- /dev/null
+++ b/tests/scm/fixtures/tfs-003.yaml
@@ -0,0 +1,8 @@
+scm:
+  - tfs:
+      server-url: "tfs.company.com"
+      project-path: "$/myproject"
+      login: "mydomain\\\\jane"
+      use-update: false
+      local-path: "../foo/"
+      workspace: "Hudson-${JOB_NAME}"