doc: updates considering website being live nowtiagogomes/docs-improvements

* Add a link to the website on the main page.
* Remove install instructions as they are now on the website.
* Remove Resources section as that information can be found at the
  website, and also looks bad.
* Move artifact server setup from the no longer existing Install section
  to the Using section.

10 files changed, 6 insertions, 480 deletions

diff --git a/doc/source/index.rst b/doc/source/index.rst
index c72489be2..c00ac7db8 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -13,20 +13,14 @@ They begin with a basic introduction to BuildStream, background
 information on basic concepts, and a guide to the BuildStream command line interface.
 Later sections provide detailed information on BuildStream internals.
 
+If you are looking for information about how to install BuildStream,
+please refer to the `BuildStream website <https://buildstream.build>`_.
 
 .. toctree::
    :maxdepth: 2
 
    main_about
-   main_install
    main_using
    main_core
    CONTRIBUTING
 
-
-Resources
----------
-* GitLab repository: https://gitlab.com/BuildStream/buildstream
-* Bug Tracking: https://gitlab.com/BuildStream/buildstream/issues
-* Mailing list: https://mail.gnome.org/mailman/listinfo/buildstream-list
-* IRC Channel: irc://irc.gnome.org/#buildstream
diff --git a/doc/source/install_docker.rst b/doc/source/install_docker.rst
deleted file mode 100644
index c1ca7a298..000000000
--- a/doc/source/install_docker.rst
+++ /dev/null
@@ -1,45 +0,0 @@
-
-
-.. _docker:
-
-BuildStream inside Docker
--------------------------
-If your system cannot provide the base system requirements for BuildStream, then it is possible to run buildstream within a Docker image.
-
-The BuildStream project provides
-`Docker images <https://hub.docker.com/r/buildstream/buildstream-fedora>`_
-containing BuildStream and its dependencies.
-This gives you an easy way to get started using BuildStream on any Unix-like
-platform where Docker is available, including Mac OS X.
-
-We recommend using the
-`bst-here wrapper script <https://gitlab.com/BuildStream/buildstream/blob/master/contrib/bst-here>`_
-which automates the necessary container setup. You can download it and make
-it executable like this:
-
-.. code:: bash
-
-  mkdir -p ~/.local/bin
-  curl --get https://gitlab.com/BuildStream/buildstream/raw/master/contrib/bst-here > ~/.local/bin/bst-here
-  chmod +x ~/.local/bin/bst-here
-
-Check if ``~/.local/bin`` appears in your PATH environment variable -- if it
-doesn't, you should
-`edit your ~/.profile so that it does <https://stackoverflow.com/questions/14637979/>`_.
-
-Once the script is available in your PATH, you can run ``bst-here`` to open a
-shell session inside a new container based off the latest version of the
-buildstream-fedora Docker image. The current working directory will be mounted
-inside the container at ``/src``.
-
-You can also run individual BuildStream commands as ``bst-here COMMAND``. For
-example: ``bst-here show systems/my-system.bst``. Note that BuildStream won't
-be able to integrate with Bash tab-completion if you invoke it in this way.
-
-Two Docker volumes are set up by the ``bst-here`` script:
-
- * ``buildstream-cache --`` mounted at ``~/.cache/buildstream``
- * ``buildstream-config --`` mounted at ``~/.config/``
-
-These are necessary so that your BuildStream cache and configuration files
-persist between invocations of ``bst-here``.
diff --git a/doc/source/install_linux_distro.rst b/doc/source/install_linux_distro.rst
deleted file mode 100644
index a547d4e8c..000000000
--- a/doc/source/install_linux_distro.rst
+++ /dev/null
@@ -1,30 +0,0 @@
-
-
-.. _install_linux_distro:
-
-Installing from distro packages
-===============================
-BuildStream is available on some linux distributions, here are
-some install instructions for the linux distributions which
-have packaged BuildStream.
-
-
-Arch Linux
-----------
-Packages for Arch exist in `AUR <https://wiki.archlinux.org/index.php/Arch_User_Repository#Installing_packages>`_.
-Two different package versions are available:
-
-* Latest release: `buildstream <https://aur.archlinux.org/packages/buildstream>`_
-* Latest development snapshot: `buildstream-git <https://aur.archlinux.org/packages/buildstream-git>`_
-
-
-Fedora
-------
-BuildStream is not yet in the official Fedora repositories, but you can
-install it from a Copr::
-
-  sudo dnf copr enable bochecha/buildstream
-  sudo dnf install buildstream
-
-Optionally, install the ``buildstream-docs`` package to have the BuildStream
-documentation in Devhelp or GNOME Builder.
diff --git a/doc/source/install_source.rst b/doc/source/install_source.rst
deleted file mode 100644
index bcd089844..000000000
--- a/doc/source/install_source.rst
+++ /dev/null
@@ -1,289 +0,0 @@
-
-
-Installing from source
-======================
-Until BuildStream is available in :ref:`your distro <install_linux_distro>`, you will
-need to install it yourself from source.
-
-
-Installing dependencies
------------------------
-Before installing BuildStream from source, it is necessary to first install
-the system dependencies. Below are some linux distribution specific instructions
-for installing these dependencies.
-
-BuildStream requires the following base system requirements:
-
-* python3 >= 3.5
-* bubblewrap >= 0.1.2
-* fuse2
-
-BuildStream also depends on the host tools for the :mod:`Source <buildstream.source>` plugins.
-Refer to the respective :ref:`source plugin <plugins_sources>` documentation for host tool
-requirements of specific plugins.
-
-The default plugins with extra host dependencies are:
-
-* bzr
-* deb
-* git
-* ostree
-* patch
-* pip
-* tar
-
-If you intend to push built artifacts to a remote artifact server,
-which requires special permissions, you will also need:
-
-* ssh
-
-
-Arch Linux
-~~~~~~~~~~
-Install the dependencies with::
-
-  sudo pacman -S \
-      python fuse2 bubblewrap \
-      python-pip
-
-For the default plugins::
-
-  sudo pacman -S \
-      bzr git lzip ostree patch python-gobject
-
-
-The package *python-arpy* is required by the deb source plugin. This is not
-obtainable via `pacman`, you must get *python-arpy* from AUR:
-https://aur.archlinux.org/packages/python-arpy/
-
-To install::
-
-  wget https://aur.archlinux.org/cgit/aur.git/snapshot/python-arpy.tar.gz
-  tar -xvf python-arpy.tar.gz
-  cd python-arpy
-  makepkg -si
-
-
-Debian
-~~~~~~
-Install the dependencies with::
-
-  sudo apt-get install \
-      python3 fuse bubblewrap \
-      python3-pip python3-dev
-
-For the default plugins:
-
-
-Stretch
-+++++++
-With stretch, you first need to ensure that you have the backports repository
-setup as described `here <https://backports.debian.org/Instructions/>`_
-
-By adding the following line to your sources.list::
-
-  deb http://deb.debian.org/debian stretch-backports main
-
-And then running::
-
-  sudo apt update
-
-At this point you should be able to get the system requirements for the default plugins with::
-
-  sudo apt install \
-      bzr git lzip patch python3-arpy python3-gi
-  sudo apt install -t stretch-backports \
-      gir1.2-ostree-1.0 ostree
-
-
-Buster or Sid
-+++++++++++++
-For debian unstable or testing, only the following line should be enough
-to get the system requirements for the default plugins installed::
-
-  sudo apt-get install \
-      lzip gir1.2-ostree-1.0 git bzr ostree patch python3-arpy python3-gi
-
-
-Fedora
-~~~~~~
-For recent fedora systems, the following line should get you the system
-requirements you need::
-
-  dnf install -y \
-      python3 fuse bubblewrap \
-      python3-pip python3-devel
-
-For the default plugins::
-
-  dnf install -y \
-      bzr git lzip patch ostree python3-gobject
-  pip3 install --user arpy
-
-
-Ubuntu
-~~~~~~
-
-
-Ubuntu 18.04 LTS or later
-+++++++++++++++++++++++++
-Install the dependencies with::
-
-  sudo apt install \
-      python3 fuse bubblewrap \
-      python3-pip python3-dev
-
-For the default plugins::
-
-  sudo apt install \
-      bzr gir1.2-ostree-1.0 git lzip ostree patch python3-arpy python3-gi
-
-
-Ubuntu 16.04 LTS
-++++++++++++++++
-On Ubuntu 16.04, neither `bubblewrap <https://github.com/projectatomic/bubblewrap/>`_
-or `ostree <https://github.com/ostreedev/ostree>`_ are available in the official repositories.
-You will need to install them in whichever way you see fit. Refer the the upstream documentation
-for advice on this.
-
-
-Installing
-----------
-Once you have the base system dependencies, you can install the BuildStream
-python package as a regular user.
-
-
-Installing from PyPI (recommended)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Since we only ever publish :ref:`release versions <install_semantic_versioning>` on
-PyPI, it is currently recommended to use this installation path. This will
-ensure that you always have the latest recommended version of BuildStream that
-we recommend.
-
-To install from PyPI, you will additionally require:
-
-* pip for python3 (only required for setup)
-* Python 3 development libraries and headers
-
-Simply run the following command::
-
-  pip3 install --user BuildStream
-
-This will install latest stable version of BuildStream and its pure python
-dependencies into your user's homedir in ``~/.local``.
-
-Keep following the instructions below to ensure that the ``bst``
-command is in your ``PATH`` and to enable bash completions for it.
-
-.. note::
-
-  If you want a specific version of BuildStream, you can install it using
-  ``pip install --user BuildStream==<version-number>``
-
-
-Upgrading from PyPI
-+++++++++++++++++++
-Once you have already installed BuildStream from PyPI, you can later update
-to the latest recommended version like so::
-
-  pip install --user --upgrade BuildStream
-
-
-.. _install_git_checkout:
-
-Installing from a git checkout
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To install directly from the `git repository <https://gitlab.com/BuildStream/buildstream.git>`_
-using python's ``pip`` package manager, you will additionally require:
-
-* pip for python3 (only required for setup)
-* Python 3 development libraries and headers
-* git (to checkout BuildStream)
-
-Before installing, please check the existing tags in the git repository
-and determine which version you want to install, and whether you want
-to install an official release version (recommended), or a development snapshot
-to help us out testing the bleeding edge of development. Follow the
-:ref:`semantic versioning guide <install_semantic_versioning>` to determine
-which tag you intend to install.
-
-Run the following commands::
-
-  git clone https://gitlab.com/BuildStream/buildstream.git
-  cd buildstream
-  git checkout <desired release tag>
-  pip3 install --user -e .
-
-This will install buildstream's pure python dependencies into
-your user's homedir in ``~/.local`` and will run BuildStream directly
-from the git checkout directory.
-
-Keep following the instructions below to ensure that the ``bst``
-command is in your ``PATH`` and to enable bash completions for it.
-
-.. note::
-
-   We recommend the ``-e`` option because you can upgrade your
-   installation by simply updating the checked out git repository.
-
-   If you want a full installation that is not linked to your
-   git checkout, just omit the ``-e`` option from the above commands.
-
-
-Upgrading from a git checkout
-+++++++++++++++++++++++++++++
-If you installed BuildStream from a local git checkout using ``-e`` option, all
-you need to do to upgrade BuildStream is to update your local git checkout::
-
-  cd /path/to/buildstream
-  git pull --rebase
-
-If you did not specify the ``-e`` option at install time or the dependancies
-have changed, you will need to cleanly reinstall BuildStream::
-
-  pip3 uninstall buildstream
-  cd /path/to/buildstream
-  git pull --rebase
-  pip3 install --user .
-
-.. note::
-
-   If BuildStream has added any dependencies since the last upgrade,
-   you will need to uninstall and reinstall to ensure those dependencies
-   are met, regardless of whether you have used the ``-e`` option at
-   install time.
-
-
-Post install setup
-------------------
-After having installed from source using any of the above methods, some
-setup will be required to use BuildStream.
-
-
-Adjust PATH
-~~~~~~~~~~~
-Since BuildStream is now installed under your local user's install directories,
-you need to ensure that ``PATH`` is adjusted.
-
-A regular way to do this is to add the following line to the end of your ``~/.bashrc``::
-
-  export PATH="${PATH}:${HOME}/.local/bin"
-
-.. note::
-
-   You will have to restart your terminal in order for these changes to take effect.
-
-
-Bash completions
-~~~~~~~~~~~~~~~~
-Bash completions are supported by sourcing the ``buildstream/data/bst``
-script found in the BuildStream repository. On many systems this script
-can be installed into a completions directory but when installing BuildStream
-without a package manager this is not an option.
-
-To enable completions for an installation of BuildStream you
-installed yourself from git, just append the script verbatim
-to your ``~/.bash_completion``:
-
-.. literalinclude:: ../../buildstream/data/bst
-   :language: yaml
diff --git a/doc/source/install_versions.rst b/doc/source/install_versions.rst
deleted file mode 100644
index db0e35d76..000000000
--- a/doc/source/install_versions.rst
+++ /dev/null
@@ -1,24 +0,0 @@
-
-
-.. _install_semantic_versioning:
-
-Semantic Versioning
-===================
-BuildStream follows the Semantic Versioning Convention `(SemVer) <https://semver.org/>`_,
-and uses even minor point numbers to denote releases intended for users while
-odd minor point numbers represent development snapshops.
-
-For example, for a given version number ``X.Y.Z``
- * The ``X.<even number>.*`` versions are releases intended for users.
- * The ``X.<odd number>.*`` versions are development spanshots intended for testing.
-
-If you are :ref:`installing from git <install_git_checkout>`, please look for the latest
-tag to ensure you're getting the latest release.
-
-* Latest release:
-
-  .. include:: release-badge.rst
-
-* Latest development snapshot:
-
-  .. include:: snapshot-badge.rst
diff --git a/doc/source/main_install.rst b/doc/source/main_install.rst
deleted file mode 100644
index 8890fb2cc..000000000
--- a/doc/source/main_install.rst
+++ /dev/null
@@ -1,29 +0,0 @@
-
-
-.. _install:
-
-Install
-=======
-
-.. include:: release-badge.rst
-
-.. include:: snapshot-badge.rst
-
-This section provides instructions for installing BuildStream and its
-companion artifact server on various platforms, along with any installation
-related materials.
-
-.. note::
-
-   BuildStream is currently only supported natively on Linux. Users of Unix-like
-   systems where Docker is available can still use BuildStream by following the
-   :ref:`Docker install guide <docker>`
-
-.. toctree::
-   :maxdepth: 1
-
-   install_source
-   install_linux_distro
-   install_docker
-   install_artifacts
-   install_versions
diff --git a/doc/source/main_using.rst b/doc/source/main_using.rst
index 65786e9eb..5f71ebddd 100644
--- a/doc/source/main_using.rst
+++ b/doc/source/main_using.rst
@@ -15,3 +15,4 @@ guides and information on user preferences and configuration.
    using_examples
    using_config
    using_commands
+   using_configuring_artifact_server
diff --git a/doc/source/release-badge.rst b/doc/source/release-badge.rst
deleted file mode 100644
index 3a09b7f9f..000000000
--- a/doc/source/release-badge.rst
+++ /dev/null
@@ -1,26 +0,0 @@
-
-.. Use this file to include the badge in the documentation, but not in
-   the README.rst or gitlab rendered materials, that doesnt work.
-
-   This is partly a workaround for a sphinx issue, we will be able
-   to avoid the raw html once this is implemented in sphinx:
-
-       https://github.com/sphinx-doc/sphinx/issues/2240
-
-   Using the <object> tag instead of the <img> tag which sphinx generates
-   allows the svg to be "interactive", for us this basically means that
-   the link we encode in the badge svg is used, rather than static urls
-   which need to be used around the <img> tag.
-
-   WARNING: The custom CSS on the style tag will need to change if we
-            change the theme, so that the <object> tag behaves similar
-	    to how the <img> tag is themed by the style sheets.
-
-.. raw:: html
-
-   <a class="reference external image-reference">
-     <object style="margin-bottom:24px;vertical-align:middle"
-             data="https://buildstream.gitlab.io/buildstream/_static/release.svg"
-	     type="image/svg+xml"/>
-     </object>
-   </a>
diff --git a/doc/source/snapshot-badge.rst b/doc/source/snapshot-badge.rst
deleted file mode 100644
index b4a3fc9f1..000000000
--- a/doc/source/snapshot-badge.rst
+++ /dev/null
@@ -1,26 +0,0 @@
-
-.. Use this file to include the badge in the documentation, but not in
-   the README.rst or gitlab rendered materials, that doesnt work.
-
-   This is partly a workaround for a sphinx issue, we will be able
-   to avoid the raw html once this is implemented in sphinx:
-
-       https://github.com/sphinx-doc/sphinx/issues/2240
-
-   Using the <object> tag instead of the <img> tag which sphinx generates
-   allows the svg to be "interactive", for us this basically means that
-   the link we encode in the badge svg is used, rather than static urls
-   which need to be used around the <img> tag.
-
-   WARNING: The custom CSS on the style tag will need to change if we
-            change the theme, so that the <object> tag behaves similar
-	    to how the <img> tag is themed by the style sheets.
-
-.. raw:: html
-
-   <a class="reference external image-reference">
-     <object style="margin-bottom:24px;vertical-align:middle"
-             data="https://buildstream.gitlab.io/buildstream/_static/snapshot.svg"
-	     type="image/svg+xml"/>
-     </object>
-   </a>
diff --git a/doc/source/install_artifacts.rst b/doc/source/using_configuring_artifact_server.rst
index 6bea7f548..2c4e761ba 100644
--- a/doc/source/install_artifacts.rst
+++ b/doc/source/using_configuring_artifact_server.rst
@@ -2,8 +2,8 @@
 
 .. _artifacts:
 
-Installing an artifact server
-=============================
+Configuring Artifact Server
+===========================
 BuildStream caches the results of builds in a local artifact cache, and will
 avoid building an element if there is a suitable build already present in the
 local artifact cache.
@@ -72,7 +72,7 @@ Installing the server
 ~~~~~~~~~~~~~~~~~~~~~
 You will also need to install BuildStream on the artifact server in order
 to receive uploaded artifacts over ssh. Follow the instructions for installing
-BuildStream :ref:`here <install>`
+BuildStream `here <https://buildstream.build/install.html>`_.
 
 When installing BuildStream on the artifact server, it must be installed
 in a system wide location, with ``pip3 install .`` in the BuildStream