sources: Don't redundantly document directory configuration

Instead of redundantly documenting "directory" configuration option in
each source plugin, refer to the built-in functionality documentation of
the Source class.

  * source.py: Add anchor for built-in functionality.
  * sources/plugins/*.py: Remove directory config option, and add reference to
    Source's built-in functionality.

Fixes #713.

11 files changed, 28 insertions, 34 deletions

diff --git a/buildstream/plugins/sources/bzr.py b/buildstream/plugins/sources/bzr.py
index 3afd0f04f..f52472918 100644
--- a/buildstream/plugins/sources/bzr.py
+++ b/buildstream/plugins/sources/bzr.py
@@ -31,9 +31,6 @@ bzr - stage files from a bazaar repository
    # Specify the bzr source kind
    kind: bzr
 
-   # Optionally specify a relative staging directory
-   # directory: path/to/stage
-
    # Specify the bzr url. Bazaar URLs come in many forms, see
    # `bzr help urlspec` for more information. Using an alias defined
    # in your project configuration is encouraged.
@@ -53,6 +50,8 @@ bzr - stage files from a bazaar repository
    # revision number to the one on the tip of the branch specified in 'track'.
    ref: 6622
 
+See :ref:`built-in functionality doumentation <core_source_builtins>` for
+details on common configuration options for sources.
 """
 
 import os
diff --git a/buildstream/plugins/sources/deb.py b/buildstream/plugins/sources/deb.py
index e1d4b65d1..1b7dafd31 100644
--- a/buildstream/plugins/sources/deb.py
+++ b/buildstream/plugins/sources/deb.py
@@ -33,9 +33,6 @@ deb - stage files from .deb packages
    # Specify the deb source kind
    kind: deb
 
-   # Optionally specify a relative staging directory
-   # directory: path/to/stage
-
    # Specify the deb url. Using an alias defined in your project
    # configuration is encouraged. 'bst track' will update the
    # sha256sum in 'ref' to the downloaded file's sha256sum.
@@ -47,6 +44,8 @@ deb - stage files from .deb packages
    # Specify the basedir to return only the specified dir and its children
    base-dir: ''
 
+See :ref:`built-in functionality doumentation <core_source_builtins>` for
+details on common configuration options for sources.
 """
 
 import tarfile
diff --git a/buildstream/plugins/sources/git.py b/buildstream/plugins/sources/git.py
index ced52d023..23e3369b1 100644
--- a/buildstream/plugins/sources/git.py
+++ b/buildstream/plugins/sources/git.py
@@ -32,9 +32,6 @@ git - stage files from a git repository
    # Specify the git source kind
    kind: git
 
-   # Optionally specify a relative staging directory
-   # directory: path/to/stage
-
    # Specify the repository url, using an alias defined
    # in your project configuration is recommended.
    url: upstream:foo.git
@@ -74,6 +71,9 @@ git - stage files from a git repository
        url: upstream:baz.git
        checkout: False
 
+See :ref:`built-in functionality doumentation <core_source_builtins>` for
+details on common configuration options for sources.
+
 **Configurable Warnings:**
 
 This plugin provides the following configurable warnings:
diff --git a/buildstream/plugins/sources/local.py b/buildstream/plugins/sources/local.py
index 8b18f9b59..bbb42d06a 100644
--- a/buildstream/plugins/sources/local.py
+++ b/buildstream/plugins/sources/local.py
@@ -29,11 +29,11 @@ local - stage local files and directories
    # Specify the local source kind
    kind: local
 
-   # Optionally specify a relative staging directory
-   # directory: path/to/stage
-
    # Specify the project relative path to a file or directory
    path: files/somefile.txt
+
+See :ref:`built-in functionality doumentation <core_source_builtins>` for
+details on common configuration options for sources.
 """
 
 import os
diff --git a/buildstream/plugins/sources/ostree.py b/buildstream/plugins/sources/ostree.py
index 177bdcc4f..770cfd55f 100644
--- a/buildstream/plugins/sources/ostree.py
+++ b/buildstream/plugins/sources/ostree.py
@@ -29,9 +29,6 @@ ostree - stage files from an OSTree repository
    # Specify the ostree source kind
    kind: ostree
 
-   # Optionally specify a relative staging directory
-   # directory: path/to/stage
-
    # Specify the repository url, using an alias defined
    # in your project configuration is recommended.
    url: upstream:runtime
@@ -48,6 +45,9 @@ ostree - stage files from an OSTree repository
    # For signed ostree repositories, specify a local project relative
    # path to the public verifying GPG key for this remote.
    gpg-key: keys/runtime.gpg
+
+See :ref:`built-in functionality doumentation <core_source_builtins>` for
+details on common configuration options for sources.
 """
 
 import os
diff --git a/buildstream/plugins/sources/patch.py b/buildstream/plugins/sources/patch.py
index 2fa002080..8e833b411 100644
--- a/buildstream/plugins/sources/patch.py
+++ b/buildstream/plugins/sources/patch.py
@@ -37,12 +37,11 @@ patch - apply locally stored patches
    # Specify the project relative path to a patch file
    path: files/somefile.diff
 
-   # Optionally specify the root directory for the patch
-   # directory: path/to/stage
-
    # Optionally specify the strip level, defaults to 1
    strip-level: 1
 
+See :ref:`built-in functionality doumentation <core_source_builtins>` for
+details on common configuration options for sources.
 """
 
 import os
diff --git a/buildstream/plugins/sources/pip.py b/buildstream/plugins/sources/pip.py
index 18e65c73d..6ba3a0407 100644
--- a/buildstream/plugins/sources/pip.py
+++ b/buildstream/plugins/sources/pip.py
@@ -54,19 +54,18 @@ Downloaded tarballs will be stored in a directory called ".bst_pip_downloads".
    packages:
    - flake8
 
-   # Optionally specify a relative staging directory
-   directory: path/to/stage
-
    # Specify the ref. It is a list of strings of format
    # "<package-name>==<version>", separated by "\\n".
    # Usually this will be contents of a requirements.txt file where all
    # package versions have been frozen.
    ref: "flake8==3.5.0\\nmccabe==0.6.1\\npkg-resources==0.0.0\\npycodestyle==2.3.1\\npyflakes==1.6.0"
 
+See :ref:`built-in functionality doumentation <core_source_builtins>` for
+details on common configuration options for sources.
+
 .. note::
 
    The ``pip`` plugin is available since :ref:`format version 16 <project_format_version>`
-
 """
 
 import errno
diff --git a/buildstream/plugins/sources/remote.py b/buildstream/plugins/sources/remote.py
index a0809cb10..a6b02fd1c 100644
--- a/buildstream/plugins/sources/remote.py
+++ b/buildstream/plugins/sources/remote.py
@@ -28,9 +28,6 @@ remote - stage files from remote urls
    # Specify the remote source kind
    kind: remote
 
-   # Optionally specify a relative staging directory
-   # directory: path/to/stage
-
    # Optionally specify a relative staging filename.
    # If not specified, the basename of the url will be used.
    # filename: customfilename
@@ -47,12 +44,12 @@ remote - stage files from remote urls
    # Specify the ref. It's a sha256sum of the file you download.
    ref: 6c9f6f68a131ec6381da82f2bff978083ed7f4f7991d931bfa767b7965ebc94b
 
-
+See :ref:`built-in functionality doumentation <core_source_builtins>` for
+details on common configuration options for sources.
 
 .. note::
 
    The ``remote`` plugin is available since :ref:`format version 10 <project_format_version>`
-
 """
 import os
 from buildstream import SourceError, utils
diff --git a/buildstream/plugins/sources/tar.py b/buildstream/plugins/sources/tar.py
index 8bbc8fce5..195c05958 100644
--- a/buildstream/plugins/sources/tar.py
+++ b/buildstream/plugins/sources/tar.py
@@ -32,9 +32,6 @@ tar - stage files from tar archives
    # Specify the tar source kind
    kind: tar
 
-   # Optionally specify a relative staging directory
-   # directory: path/to/stage
-
    # Specify the tar url. Using an alias defined in your project
    # configuration is encouraged. 'bst track' will update the
    # sha256sum in 'ref' to the downloaded file's sha256sum.
@@ -53,6 +50,9 @@ tar - stage files from tar archives
    # To extract the root of the tarball directly, this can be set
    # to an empty string.
    base-dir: '*'
+
+See :ref:`built-in functionality doumentation <core_source_builtins>` for
+details on common configuration options for sources.
 """
 
 import os
diff --git a/buildstream/plugins/sources/zip.py b/buildstream/plugins/sources/zip.py
index 0bbb2cd27..f5fac3a48 100644
--- a/buildstream/plugins/sources/zip.py
+++ b/buildstream/plugins/sources/zip.py
@@ -28,9 +28,6 @@ zip - stage files from zip archives
    # Specify the zip source kind
    kind: zip
 
-   # Optionally specify a relative staging directory
-   # directory: path/to/stage
-
    # Specify the zip url. Using an alias defined in your project
    # configuration is encouraged. 'bst track' will update the
    # sha256sum in 'ref' to the downloaded file's sha256sum.
@@ -50,11 +47,13 @@ zip - stage files from zip archives
    # to an empty string.
    base-dir: '*'
 
+See :ref:`built-in functionality doumentation <core_source_builtins>` for
+details on common configuration options for sources.
+
 .. attention::
 
    File permissions are not preserved. All extracted directories have
    permissions 0755 and all extracted files have permissions 0644.
-
 """
 
 import os
diff --git a/buildstream/source.py b/buildstream/source.py
index 483fd2341..af0ba0d96 100644
--- a/buildstream/source.py
+++ b/buildstream/source.py
@@ -20,6 +20,8 @@
 Source - Base source class
 ==========================
 
+.. _core_source_builtins:
+
 Built-in functionality
 ----------------------