summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorTristan Van Berkom <tristan.vanberkom@codethink.co.uk>2018-01-17 19:08:03 +0900
committerTristan Van Berkom <tristan.vanberkom@codethink.co.uk>2018-01-17 19:08:03 +0900
commit88260c7a57f9c797af3f8222c02b257b25d25d45 (patch)
tree15a87fb80b83974d99e524f30fe7debaccc8ac54 /doc
parent03412a9e8a13e6c5f50dec95e067c2ae6900d08f (diff)
downloadbuildstream-88260c7a57f9c797af3f8222c02b257b25d25d45.tar.gz
Documentation: Restructured toplevel documentationdocs-reorganization
This is intended to make things easier to find for the various types of people searching for stuff. o The installation instructions remain on the main page. o Three main separate pages have been created - Using BuildStream - Authoring BuildStream projects - Core API reference, for plugin authors o The "Authoring projects" section swallows the previous plugin index; so one can find the plugin one is looking for on the same page as the rest of the format docs o The plugin authoring section has been swallowed by the core API reference section, with a note that this is useful especially for plugin authors.
Diffstat (limited to 'doc')
-rw-r--r--doc/source/format.rst4
-rw-r--r--doc/source/index.rst58
-rw-r--r--doc/source/main_authoring.rst (renamed from doc/source/pluginindex.rst)64
-rw-r--r--doc/source/main_core.rst (renamed from doc/source/pluginauthoring.rst)18
-rw-r--r--doc/source/main_using.rst16
5 files changed, 90 insertions, 70 deletions
diff --git a/doc/source/format.rst b/doc/source/format.rst
index 6f6e2f0ec..fe4f57ea1 100644
--- a/doc/source/format.rst
+++ b/doc/source/format.rst
@@ -91,6 +91,8 @@ to the elements on which they depend here. See `Dependencies`_ for more informat
on the dependency model.
+.. _format_sources:
+
Sources
~~~~~~~
@@ -167,6 +169,8 @@ build instructions are run for this element.
Environment variables can also be declared and overridden in the :ref:`projectconf`
+.. _format_config:
+
Config
~~~~~~
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 8bf871989..36aa749bc 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -29,60 +29,12 @@ Installing
* :ref:`artifacts`
-Running
--------
-* :ref:`invoking`
-* :ref:`config`
+Documentation
+-------------
-
-Project format
---------------
-* :ref:`formatintro`
-
- * :ref:`format_structure`
- * :ref:`format_composition`
- * :ref:`format_directives`
-
-* :ref:`projectconf`
-
- * :ref:`project_essentials`
- * :ref:`project_plugins`
- * :ref:`project_options`
- * :ref:`project_defaults`
- * :ref:`project_builtin_defaults`
-
-* :ref:`format`
-
- * :ref:`format_basics`
- * :ref:`format_dependencies`
- * :ref:`format_variables`
-
-* :ref:`public`
-
-
-Builtin Plugins
----------------
-* :ref:`plugins`
-
- * :ref:`plugins_elements`
- * :ref:`plugins_sources`
-
-External Plugins
-----------------
-
-* `bst-external <http://buildstream.gitlab.io/bst-external/>`_
-
-
-Creating Plugins
-----------------
-* :ref:`pluginauthoring`
-
- * :ref:`core_framework`
-
-
-Internals
----------
-* :ref:`cachekeys`
+* :ref:`main_using`
+* :ref:`main_authoring`
+* :ref:`main_core`
Indices and tables
diff --git a/doc/source/pluginindex.rst b/doc/source/main_authoring.rst
index 57f14876d..4e118f8af 100644
--- a/doc/source/pluginindex.rst
+++ b/doc/source/main_authoring.rst
@@ -1,28 +1,64 @@
:orphan:
-.. _plugins:
-Plugins
-=======
+.. _main_authoring:
+
+Authoring Projects
+==================
+This section details how to use the BuildStream YAML format to
+create your own project or modify existing projects.
+
+
+Project format
+--------------
+* :ref:`formatintro`
+
+ * :ref:`format_structure`
+ * :ref:`format_composition`
+ * :ref:`format_directives`
+* :ref:`projectconf`
+
+ * :ref:`project_essentials`
+ * :ref:`project_plugins`
+ * :ref:`project_options`
+ * :ref:`project_defaults`
+ * :ref:`project_builtin_defaults`
+
+* :ref:`format`
+
+ * :ref:`format_basics`
+ * :ref:`format_dependencies`
+ * :ref:`format_variables`
+
+* :ref:`public`
+
+
+Plugins
+-------
+Plugins provide their own individual plugin specific YAML configurations,
+The element ``.bst`` files can specify plugin specific configuration in
+the :ref:`config section <format_config>`, while sources declared on a
+given element specify their plugin specific configuration
+:ref:`directly on their main dictionary <format_sources>`.
-.. _plugins_elements:
Elements
---------
+~~~~~~~~
The following element types are provided with BuildStream:
General Elements
-~~~~~~~~~~~~~~~~
+''''''''''''''''
* :mod:`stack <elements.stack>` - Symbolic Element for dependency grouping
* :mod:`import <elements.import>` - Import sources directly
* :mod:`compose <elements.compose>` - Compose the output of multiple elements
* :mod:`script <elements.script>` - Run scripts to create output
+
Build Elements
-~~~~~~~~~~~~~~
+''''''''''''''
* :mod:`manual <elements.manual>` - Manual Build Element
* :mod:`autotools <elements.autotools>` - Autotools Build Element
@@ -35,11 +71,8 @@ Build Elements
* :mod:`pip <elements.pip>` - Pip build element
-.. _plugins_sources:
-
-
Sources
---------
+~~~~~~~
The following source types are provided with BuildStream:
* :mod:`local <sources.local>` - A Source implementation for local files and directories
@@ -49,3 +82,12 @@ The following source types are provided with BuildStream:
* :mod:`bzr <sources.bzr>` - A Source implementation for bazaar
* :mod:`ostree <sources.ostree>` - A Source implementation for ostree
* :mod:`patch <sources.patch>` - A Source implementation for applying local patches
+
+
+
+External Plugins
+----------------
+External plugins need to be installed separately, here is
+a list of BuildStream plugin projects known to us at this time:
+
+* `bst-external <http://buildstream.gitlab.io/bst-external/>`_
diff --git a/doc/source/pluginauthoring.rst b/doc/source/main_core.rst
index c42bd575b..b14413591 100644
--- a/doc/source/pluginauthoring.rst
+++ b/doc/source/main_core.rst
@@ -1,12 +1,12 @@
:orphan:
-.. _pluginauthoring:
+.. _main_core:
-Authoring Plugins
-=================
-Here we try to provide any additional documentation one will need
-to create their own custom plugins to use with BuildStream.
+Core documentation and reference
+================================
+This section details the core API reference along with
+other more elaborate details about BuildStream internals.
.. _core_framework:
@@ -15,7 +15,8 @@ Core Framework
--------------
The core public APIs are of interest to anyone who wishes to
implement custom :mod:`Element <buildstream.element>` or
-:mod:`Source <buildstream.source>` plugins.
+:mod:`Source <buildstream.source>` plugins, and can also be
+useful for working on BuildStream itself.
* :mod:`Plugin <buildstream.plugin>` - Base Class for all plugins
* :mod:`Source <buildstream.source>` - Base Source Class
@@ -24,3 +25,8 @@ implement custom :mod:`Element <buildstream.element>` or
* :mod:`ScriptElement <buildstream.scriptelement>` - Script Element Class
* :mod:`Sandbox <buildstream.sandbox.sandbox>` - Build Sandbox
* :mod:`Utilities <buildstream.utils>` - Utilities for Plugins
+
+
+Internals
+---------
+* :ref:`cachekeys`
diff --git a/doc/source/main_using.rst b/doc/source/main_using.rst
new file mode 100644
index 000000000..b817e0cda
--- /dev/null
+++ b/doc/source/main_using.rst
@@ -0,0 +1,16 @@
+:orphan:
+
+
+.. _main_using:
+
+Using BuildStream
+=================
+This section details how to use the BuildStream command line interface
+and work with existing BuildStream projects.
+
+For details on how to modify an existing BuildStream project or create
+a new one, refer to :ref:`main_authoring`.
+
+
+* :ref:`invoking`
+* :ref:`config`