This is an automated email from the ASF dual-hosted git repository. tvb pushed a commit to branch tiagogomes/docs-improvements in repository https://gitbox.apache.org/repos/asf/buildstream.git
commit 875496d2c50ecbb9defb964e1c10a66ae0c11b6b Author: Tiago Gomes <[email protected]> AuthorDate: Fri Sep 28 11:24:44 2018 +0100 doc: updates considering website being live now * 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. --- doc/source/index.rst | 10 +- doc/source/install_docker.rst | 45 ---- doc/source/install_linux_distro.rst | 30 --- doc/source/install_source.rst | 289 --------------------- doc/source/install_versions.rst | 24 -- doc/source/main_install.rst | 29 --- doc/source/main_using.rst | 1 + doc/source/release-badge.rst | 26 -- doc/source/snapshot-badge.rst | 26 -- ...s.rst => using_configuring_artifact_server.rst} | 6 +- 10 files changed, 6 insertions(+), 480 deletions(-) diff --git a/doc/source/index.rst b/doc/source/index.rst index c72489b..c00ac7d 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 c1ca7a2..0000000 --- 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 a547d4e..0000000 --- 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 bcd0898..0000000 --- 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 db0e35d..0000000 --- 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 8890fb2..0000000 --- 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 65786e9..5f71ebd 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 3a09b7f..0000000 --- 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 b4a3fc9..0000000 --- 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 similarity index 98% rename from doc/source/install_artifacts.rst rename to doc/source/using_configuring_artifact_server.rst index 6bea7f5..2c4e761 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
![https://buildstream.gitlab.io/buildstream/_static/release.svg"](https://buildstream.gitlab.io/buildstream/_static/release.svg"){kind=link}
![https://buildstream.gitlab.io/buildstream/_static/snapshot.svg"](https://buildstream.gitlab.io/buildstream/_static/snapshot.svg"){kind=link}