Merge branch 'chandan/source-doc-directory' into 'master'

plugins: Don't redundantly document common configurations

Closes #713

See merge request BuildStream/buildstream!896

23 files changed, 63 insertions, 34 deletions

diff --git a/buildstream/buildelement.py b/buildstream/buildelement.py
index e57ca1c79..48b7f2423 100644
--- a/buildstream/buildelement.py
+++ b/buildstream/buildelement.py
@@ -23,6 +23,8 @@ BuildElement - Abstract class for build elements
 The BuildElement class is a convenience element one can derive from for
 implementing the most common case of element.
 
+.. _core_buildelement_builtins:
+
 Built-in functionality
 ----------------------
 
diff --git a/buildstream/plugins/elements/autotools.py b/buildstream/plugins/elements/autotools.py
index cf5e85661..43fe7add4 100644
--- a/buildstream/plugins/elements/autotools.py
+++ b/buildstream/plugins/elements/autotools.py
@@ -50,6 +50,9 @@ Here is the default configuration for the ``autotools`` element in full:
 
   .. literalinclude:: ../../../buildstream/plugins/elements/autotools.yaml
      :language: yaml
+
+See :ref:`built-in functionality documentation <core_buildelement_builtins>` for
+details on common configuration options for build elements.
 """
 
 from buildstream import BuildElement
diff --git a/buildstream/plugins/elements/cmake.py b/buildstream/plugins/elements/cmake.py
index 2cb2601ae..de9aa9616 100644
--- a/buildstream/plugins/elements/cmake.py
+++ b/buildstream/plugins/elements/cmake.py
@@ -49,6 +49,9 @@ Here is the default configuration for the ``cmake`` element in full:
 
   .. literalinclude:: ../../../buildstream/plugins/elements/cmake.yaml
      :language: yaml
+
+See :ref:`built-in functionality documentation <core_buildelement_builtins>` for
+details on common configuration options for build elements.
 """
 
 from buildstream import BuildElement
diff --git a/buildstream/plugins/elements/distutils.py b/buildstream/plugins/elements/distutils.py
index 5201013c1..20a2d67ef 100644
--- a/buildstream/plugins/elements/distutils.py
+++ b/buildstream/plugins/elements/distutils.py
@@ -26,6 +26,9 @@ python distutils
 The distutils default configuration:
   .. literalinclude:: ../../../buildstream/plugins/elements/distutils.yaml
      :language: yaml
+
+See :ref:`built-in functionality documentation <core_buildelement_builtins>` for
+details on common configuration options for build elements.
 """
 
 from buildstream import BuildElement
diff --git a/buildstream/plugins/elements/import.py b/buildstream/plugins/elements/import.py
index 0eca2a902..ec491a0a5 100644
--- a/buildstream/plugins/elements/import.py
+++ b/buildstream/plugins/elements/import.py
@@ -28,6 +28,9 @@ some configuration data.
 The empty configuration is as such:
   .. literalinclude:: ../../../buildstream/plugins/elements/import.yaml
      :language: yaml
+
+See :ref:`built-in functionality documentation <core_buildelement_builtins>` for
+details on common configuration options for build elements.
 """
 
 import os
diff --git a/buildstream/plugins/elements/make.py b/buildstream/plugins/elements/make.py
index 6c500f3f9..a22de168a 100644
--- a/buildstream/plugins/elements/make.py
+++ b/buildstream/plugins/elements/make.py
@@ -31,6 +31,9 @@ Here is the default configuration for the ``make`` element in full:
 
   .. literalinclude:: ../../../buildstream/plugins/elements/make.yaml
      :language: yaml
+
+See :ref:`built-in functionality documentation <core_buildelement_builtins>` for
+details on common configuration options for build elements.
 """
 
 from buildstream import BuildElement
diff --git a/buildstream/plugins/elements/makemaker.py b/buildstream/plugins/elements/makemaker.py
index fccfaadab..8ad979984 100644
--- a/buildstream/plugins/elements/makemaker.py
+++ b/buildstream/plugins/elements/makemaker.py
@@ -26,6 +26,9 @@ the Perl ExtUtil::MakeMaker build system
 The MakeMaker default configuration:
   .. literalinclude:: ../../../buildstream/plugins/elements/makemaker.yaml
      :language: yaml
+
+See :ref:`built-in functionality documentation <core_buildelement_builtins>` for
+details on common configuration options for build elements.
 """
 
 from buildstream import BuildElement
diff --git a/buildstream/plugins/elements/manual.py b/buildstream/plugins/elements/manual.py
index c7bdba95f..3300d017a 100644
--- a/buildstream/plugins/elements/manual.py
+++ b/buildstream/plugins/elements/manual.py
@@ -26,6 +26,9 @@ add custom build commands to the array understood by the :mod:`BuildElement <bui
 The empty configuration is as such:
   .. literalinclude:: ../../../buildstream/plugins/elements/manual.yaml
      :language: yaml
+
+See :ref:`built-in functionality documentation <core_buildelement_builtins>` for
+details on common configuration options for build elements.
 """
 
 from buildstream import BuildElement
diff --git a/buildstream/plugins/elements/meson.py b/buildstream/plugins/elements/meson.py
index 9e0edf19e..0d5ca0087 100644
--- a/buildstream/plugins/elements/meson.py
+++ b/buildstream/plugins/elements/meson.py
@@ -46,6 +46,9 @@ Here is the default configuration for the ``meson`` element in full:
 
   .. literalinclude:: ../../../buildstream/plugins/elements/meson.yaml
      :language: yaml
+
+See :ref:`built-in functionality documentation <core_buildelement_builtins>` for
+details on common configuration options for build elements.
 """
 
 from buildstream import BuildElement
diff --git a/buildstream/plugins/elements/modulebuild.py b/buildstream/plugins/elements/modulebuild.py
index 5189af1a6..d619a1d01 100644
--- a/buildstream/plugins/elements/modulebuild.py
+++ b/buildstream/plugins/elements/modulebuild.py
@@ -26,6 +26,9 @@ the Perl Module::Build build system
 The modulebuild default configuration:
   .. literalinclude:: ../../../buildstream/plugins/elements/modulebuild.yaml
      :language: yaml
+
+See :ref:`built-in functionality documentation <core_buildelement_builtins>` for
+details on common configuration options for build elements.
 """
 
 from buildstream import BuildElement
diff --git a/buildstream/plugins/elements/pip.py b/buildstream/plugins/elements/pip.py
index e62f713a6..02b593af3 100644
--- a/buildstream/plugins/elements/pip.py
+++ b/buildstream/plugins/elements/pip.py
@@ -26,6 +26,9 @@ Python modules with pip
 The pip default configuration:
   .. literalinclude:: ../../../buildstream/plugins/elements/pip.yaml
      :language: yaml
+
+See :ref:`built-in functionality documentation <core_buildelement_builtins>` for
+details on common configuration options for build elements.
 """
 
 from buildstream import BuildElement
diff --git a/buildstream/plugins/elements/qmake.py b/buildstream/plugins/elements/qmake.py
index 9f5bc4018..d6776b0b2 100644
--- a/buildstream/plugins/elements/qmake.py
+++ b/buildstream/plugins/elements/qmake.py
@@ -26,6 +26,9 @@ the qmake build system
 The qmake default configuration:
   .. literalinclude:: ../../../buildstream/plugins/elements/qmake.yaml
      :language: yaml
+
+See :ref:`built-in functionality documentation <core_buildelement_builtins>` for
+details on common configuration options for build elements.
 """
 
 from buildstream import BuildElement
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
 ----------------------